ข้ามไปยังเนื้อหา
การนำทางเอกสาร

เริ่มที่นี่

ผลิตภัณฑ์

การเชื่อมต่อ

SDK

MCP

OAuth and protocol

Discovery and endpoints

The canonical server URL is https://upweight.dev/mcp. The issuer and resource derive from the configured server origin, not request headers.

EndpointPurpose
POST /mcpAuthenticated stateless JSON-RPC requests.
GET /mcp, DELETE /mcpHTTP 405, Allow: POST. No SSE or session lifecycle.
GET /.well-known/oauth-protected-resource/mcpProtected-resource metadata.
GET /.well-known/oauth-protected-resourceAlias of the same metadata.
GET /.well-known/oauth-authorization-serverAuthorization-server metadata.
GET/POST /oauth/authorizeBrowser sign-in and consent.
POST /oauth/tokenAuthorization-code exchange and refresh rotation.

Client identity and PKCE

CIMD-only public clients identify themselves with a public HTTPS client metadata document URL. This URL is distinct from the registered redirect URI and canonical MCP resource. There is no dynamic client registration (DCR), personal access token (PAT), or manual client secret. Token authentication method is none.

Authorization-code flow requires PKCE S256 and a redirect matching client metadata. The resource is the canonical issuer plus /mcp; a different resource is rejected. Authorization responses include the issuer in iss.

Tokens and rotation

Authorization codes expire in 600 seconds. Access tokens expire in 3600 seconds. Refresh tokens expire in 30 days and rotate on every use. Refresh tokens are single-use; reuse revokes the entire token family. Tokens are stored as SHA-256 hashes. Never share raw tokens, codes or PKCE verifiers. Token responses are marked no-store and no-cache.

The four scopes are feedback:read, feedback:write, changelog:read and changelog:write. Omitted consent scope requests all four; write does not imply read.

Protocol versions

Preferred: 2026-07-28. Supported legacy versions: 2025-11-25 and 2025-06-18. Modern clients use server/discover, tools/list and tools/call. Legacy clients negotiate with initialize and may use ping. Headerless legacy initialization falls back to the newest legacy version when needed; subsequent legacy requests send a supported MCP-Protocol-Version header.

Request and response contract

Use stateless POST with one bearer authorization header and Content-Type: application/json. Responses are JSON, not persistent event streams. GET and DELETE return 405. There is no SSE or session lifecycle. Envelopes are body-only: query parameters cannot replace methods, IDs, arguments or metadata. Batches are rejected. If an Origin header is sent, it must match the server origin.

Every modern request must include a matching MCP-Protocol-Version header and params._meta.io.modelcontextprotocol/protocolVersion value, a Mcp-Method header matching the method, and a client capabilities object at params._meta.io.modelcontextprotocol/clientCapabilities. For tools/call, Mcp-Name must match the tool name; for other methods it must be absent.

Accepted notifications (without an id) return 202 with an empty body and no tool effects. Accepted client result/error envelopes also return empty 202 responses. Validation and authentication can still reject a notification before dispatch.

Errors

Distinguish four layers; HTTP 200 alone does not prove a tool succeeded.

LayerMeaning
HTTP401 invalid or missing bearer or lost grant; 402 billing required; 403 insufficient scope or origin mismatch; 405 unsupported transport; 429 rate limited with Retry-After in seconds. Media negotiation can return 406 or 415.
JSON-RPCProtocol validation uses HTTP 400. Codes include -32600 invalid request, -32601 unknown method, -32602 invalid parameters or unknown tool, -32020 transport/header mismatch, -32021 missing capabilities, -32022 unsupported version with supported versions. Dispatcher errors normally use HTTP 200; insufficient scope uses HTTP 403 and -32003.
Tool resultKnown-tool argument or business failures return HTTP 200 with result.isError: true and readable text, not a JSON-RPC error. Successful results contain structuredContent and matching JSON text.
OAuthThe token endpoint uses OAuth JSON errors, not JSON-RPC: HTTP 401 invalid_client, or HTTP 400 invalid_request, invalid_target, invalid_grant (including refresh reuse), unsupported_grant_type. Its Basic challenge does not mean client secrets are supported.

See MCP troubleshooting for recovery steps.

ตรวจสอบล่าสุด