MCP Server Schema

Top-level fields

Field	Type	Required	Description
name	string	yes	Display name for your MCP server
slug	string	yes	URL identifier — your server becomes available at /mcp/{slug}
description	string	no	Short description of what the server does
authentication	object	no	Server-level auth applied to every tool call (see below)
oauth	object	no	OAuth 2.0 configuration for user-delegated auth flows (see below)
tools	array	yes	List of tools your server exposes (see below)

authentication object

Defines how the caller's API token is forwarded to your upstream service. When present, Shredly automatically injects the token into every outbound request using the specified scheme.

Field	Type	Required	Description
type	string	yes	Auth scheme: Bearer (prepends "Bearer "), ApiKey (sends the raw token), Basic (prepends "Basic "), or QueryParam (appends the token as a query parameter)
header	string	no	Override header name for Bearer, ApiKey, or Basic — e.g. X-My-Key
query_key	string	no	Query parameter name when type is QueryParam — defaults to api_key

{
  "authentication": {
    "type": "Bearer"
  }
}

Using ApiKey with a custom header name:

{
  "authentication": {
    "type": "ApiKey",
    "header": "X-My-Key"
  }
}

oauth object

Configures an OAuth 2.0 authorization code flow for your server. When present, Shredly handles the redirect and token exchange on behalf of the user.

Field	Type	Required	Description
authorization_url	string	yes	The provider's authorization endpoint where users are redirected to grant access
token_url	string	yes	The endpoint Shredly calls to exchange an authorization code for an access token
client_id	string	yes	Your OAuth application's client ID
client_secret	string	yes	Your OAuth application's client secret
scopes	array	yes	List of OAuth scopes to request — e.g. ["openid", "profile", "email"]
extra_params	object	no	Additional query parameters appended to the authorization URL — e.g. {"access_type": "offline"} for refresh tokens

{
  "oauth": {
    "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth",
    "token_url": "https://your-backend.com/oauth/token",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "scopes": ["openid", "profile", "email"],
    "extra_params": {
      "access_type": "offline"
    }
  }
}

tools array

Each entry describes one callable tool. All fields are required.

Field	Type	Description
name	string	Tool name exposed to the MCP client
description	string	Natural-language description of what the tool does
method	string	HTTP verb: GET, POST, PUT, PATCH, or DELETE
url	string	Upstream URL. Supports :param path templates (e.g. /users/:id). For GET requests, any input_schema args not consumed by a path template are automatically appended as query string parameters.
headers	object	Static key/value headers sent on every request (e.g. {"Content-Type": "application/json"})
input_schema	object	Flat map of argument name → field definition. Each field has a type (string, number, etc.) and optional description and optional: true.
response_transform	string	Dot-path into the response JSON to extract — e.g. data.results. Use . to return the full response.
timeout_ms	number	Request timeout in milliseconds. Maximum 20000.

URL templates and GET query parameters

The url field supports two mechanisms for injecting input_schema arguments into requests:

Path templates — use :param tokens anywhere in the URL (path or query string). Shredly replaces each token with the corresponding argument value before sending the request.

Automatic query parameters (GET only) — for GET requests, any input_schema arguments not consumed by a path template are automatically appended to the URL as query string parameters.

These two mechanisms compose: you can use path templates for some arguments and let the rest fall through as query params.

Example — simple GET with query params:

{
  "name": "listProjects",
  "description": "List projects, optionally filtered by status.",
  "method": "GET",
  "url": "https://api.yourapp.com/projects",
  "headers": {},
  "input_schema": {
    "status": {
      "type": "string",
      "description": "Filter by status (e.g. active, archived)",
      "optional": true
    }
  },
  "response_transform": ".",
  "timeout_ms": 5000
}

Called with { "status": "active" } → GET /projects?status=active

Example — path template for resource ID:

{
  "name": "getProject",
  "description": "Fetch a single project by ID.",
  "method": "GET",
  "url": "https://api.yourapp.com/projects/:id",
  "headers": {},
  "input_schema": {
    "id": {
      "type": "string",
      "description": "The project ID"
    }
  },
  "response_transform": ".",
  "timeout_ms": 5000
}

Called with { "id": "proj_123" } → GET /projects/proj_123

Example — PostgREST / Supabase filter syntax:

PostgREST-style APIs (like Supabase) use query param values in the form eq.{value}. Embed the operator prefix directly in the URL template so callers only need to pass the plain value:

{
  "name": "getProjectById",
  "description": "Fetch a project from Supabase by ID.",
  "method": "GET",
  "url": "https://<project>.supabase.co/rest/v1/projects?id=eq.:id",
  "headers": {
    "apikey": "<your-supabase-anon-key>"
  },
  "input_schema": {
    "id": {
      "type": "string",
      "description": "The project UUID"
    }
  },
  "response_transform": ".",
  "timeout_ms": 5000
}

Called with { "id": "abc-123" } → GET /rest/v1/projects?id=eq.abc-123

Example tool definition:

{
  "name": "getUser",
  "description": "Fetch a user by ID from your backend.",
  "method": "GET",
  "url": "https://api.yourapp.com/users/:user_id",
  "headers": {
    "Content-Type": "application/json"
  },
  "input_schema": {
    "user_id": {
      "type": "string",
      "description": "The ID of the user to fetch"
    }
  },
  "response_transform": "data",
  "timeout_ms": 5000
}

Example full server configuration:

{
  "name": "My App MCP",
  "slug": "my-app",
  "description": "MCP server for My App",
  "authentication": {
    "type": "Bearer"
  },
  "oauth": {
    "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth",
    "token_url": "https://your-backend.com/oauth/token",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "scopes": ["openid", "profile", "email"],
    "extra_params": {
      "access_type": "offline"
    }
  },
  "tools": [
    {
      "name": "createRecord",
      "description": "Create a new record in My App.",
      "method": "POST",
      "url": "https://api.yourapp.com/records",
      "headers": {
        "Content-Type": "application/json"
      },
      "input_schema": {
        "title": {
          "type": "string"
        }
      },
      "response_transform": ".",
      "timeout_ms": 10000
    }
  ]
}