MCP
The MCP endpoint and the OAuth discovery documents MCP clients read.
- POST
/mcp - GET
/.well-known/oauth-protected-resource - GET
/.well-known/oauth-protected-resource/mcp - GET
/.well-known/oauth-authorization-server
MCP endpoint (JSON-RPC)
POST /mcp
Credential: None, or Secret key (Authorization: Bearer spk_live_…), or Secret key in X-API-Key, or MCP sign-in (Authorization: Bearer oat_…)
Stateless, POST-only MCP (streamable HTTP, JSON responses). Tools are described in
the MCP page. initialize, tools/list, resources/*, prompts/*,
ping and the public tools work without a credential. 401 with WWW-Authenticate is
returned only when a protected tools/call has no credential, or any credential is unknown,
revoked or expired; all other failures are tool errors with 200. GET/DELETE → 405.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
MCP-Protocol-Version | header | string | |
Mcp-Method | header | string | When present, must equal the body's method. |
Mcp-Name | header | string | When present, must equal the body's params.name / params.uri. |
Request body
application/json
| Field | Type | Description |
|---|---|---|
jsonrpc required | 2.0 | |
id | string | integer | null | |
method | string | |
params | object | |
result | object | |
error | object | |
error.code required | integer | |
error.message required | string | |
error.data | any |
Responses
200 JSON-RPC response.
| Field | Type | Description |
|---|---|---|
jsonrpc required | 2.0 | |
id | string | integer | null | |
method | string | |
params | object | |
result | object | |
error | object | |
error.code required | integer | |
error.message required | string | |
error.data | any |
202 JSON-RPC notification accepted (empty body).
| Status | Error codes |
|---|---|
| 400 | Header/body mismatch (JSON-RPC error -32020) or malformed JSON-RPC. |
| 401 | Missing credential on a protected tool call, or an invalid credential. |
Protected resource metadata (RFC 9728)
GET /.well-known/oauth-protected-resource
Credential: None
Same body as /.well-known/oauth-protected-resource/mcp. Cache-Control: public, max-age=300.
Responses
200 Metadata.
| Field | Type | Description |
|---|---|---|
resource required | string | Format uri. Example https://sparka.io/mcp. |
authorization_servers required | array of string | |
scopes_supported required | array of string | |
bearer_methods_supported required | array of string | |
resource_name | string | |
resource_documentation | string | Format uri. |
| Status | Error codes |
|---|---|
| 429 | rate_limited, with retry_after_s. |
Protected resource metadata for /mcp (RFC 9728)
GET /.well-known/oauth-protected-resource/mcp
Credential: None
Cache-Control: public, max-age=300.
Responses
200 Metadata.
| Field | Type | Description |
|---|---|---|
resource required | string | Format uri. Example https://sparka.io/mcp. |
authorization_servers required | array of string | |
scopes_supported required | array of string | |
bearer_methods_supported required | array of string | |
resource_name | string | |
resource_documentation | string | Format uri. |
| Status | Error codes |
|---|---|
| 429 | rate_limited, with retry_after_s. |
Authorization server metadata (RFC 8414)
GET /.well-known/oauth-authorization-server
Credential: None
Cache-Control: public, max-age=300. There is no /.well-known/openid-configuration.
Responses
200 Metadata.
| Field | Type | Description |
|---|---|---|
issuer required | string | Format uri. |
authorization_endpoint required | string | Format uri. |
token_endpoint required | string | Format uri. |
registration_endpoint required | string | Format uri. |
revocation_endpoint required | string | Format uri. |
scopes_supported | array of string | |
response_types_supported required | array of string | |
response_modes_supported | array of string | |
grant_types_supported required | array of string | |
token_endpoint_auth_methods_supported required | array of string | |
revocation_endpoint_auth_methods_supported | array of string | |
code_challenge_methods_supported required | array of string | |
client_id_metadata_document_supported | boolean | |
authorization_response_iss_parameter_supported | boolean | |
service_documentation | string | Format uri. |
| Status | Error codes |
|---|---|
| 429 | rate_limited, with retry_after_s. |