MCP

The same workspace, exposed as tools to an AI client. This is the endpoint you paste into Claude Desktop, Claude Code, or anything else that speaks the Model Context Protocol.

https://gateway.praxsuite.com/{workspaceId}/mcp

Transport: Streamable HTTP. POST carries JSON-RPC 2.0; GET opens the SSE channel a client expects to find, which stays empty because this server works request-response.

Protocol version: 2024-11-05. Server: praxsuite.

Connecting

{
  "mcpServers": {
    "praxsuite": {
      "type": "http",
      "url": "https://gateway.praxsuite.com/{workspaceId}/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Who may call it

Four gates, checked in order, each with its own message:

1. A credential is required. No key, no call.

2. It must belong to this workspace, or 403.

3. It must be an API key or a registered AI connector. An end-user JWT is refused outright — the MCP surface creates API keys, deploys apps and manages users, which is nothing a logged-in app user was ever granted. Use /query for end-user data access.

4. The key must be enabled for MCP, a switch on the key itself. A credential meant for REST use only is off MCP entirely until an administrator turns it on.

Beyond that, the tools a caller sees are narrowed by its MCP capability grants: tools/list returns only what this credential may actually use, so an unavailable tool is absent rather than present-and-failing.

Methods

Anything else is JSON-RPC error -32601. A body that is not valid JSON is -32700.

Errors

JSON-RPC, not the HTTP error shapes used elsewhere:

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32001, "message": "…" } }

-32001 is the authentication and authorization code — all four gates above report through it, with the reason in message. Note that the HTTP status can be 401 or 403 while the body is still a JSON-RPC error object.

Discovery

A client that arrives without a credential gets a 401 carrying:

WWW-Authenticate: Bearer realm="Praxsuite Gateway", resource_metadata="https://gateway.praxsuite.com/.well-known/oauth-protected-resource/{workspaceId}/mcp"

That URL is this resource's Protected Resource Metadata (RFC 9728), the document an MCP client reads to learn which authorization server guards this endpoint rather than guessing:

{
  "resource": "https://gateway.praxsuite.com/{workspaceId}/mcp",
  "authorization_servers": ["https://identity.praxsuite.com"],
  "scopes_supported": ["gateway:read", "gateway:write"],
  "bearer_methods_supported": ["header"]
}

The client then fetches that authorization server's own metadata to find the authorize and token endpoints. A root-level document at /.well-known/oauth-protected-resource, describing the gateway as a whole, is served for clients that probe before they have seen a 401.

Note that there is no registration_endpoint: dynamic client registration is not offered, so a connector is registered in the workspace rather than self-registering. See Discovery.

See also

API Gateway → Credentials → MCP Tool Permissions in the documentation, for which tools a credential can be granted and why the default is nothing.