Weavers / MCP documentation

Protocol reference

Weavers MCP transport, discovery, initialization, tool results, limits, and authentication.

Transport and discovery

The external server accepts POST requests at the URL below using Streamable HTTP with JSON responses.
Send Content-Type: application/json and Accept: application/json, text/event-stream. GET and DELETE return 405 with Allow: POST; there is no persistent event stream or server session ID.
OAuth resource metadata is available at /.well-known/oauth-protected-resource/api/mcp on the same origin. Follow its authorization_servers value to discover authorization-server metadata.
The public server registers tools. It does not register MCP resources or reusable prompts. Example prompts in this guide are conversation suggestions.

Transport and discovery

https://www.weavers.app/api/mcp

Initialize, discover, then call

Let your MCP client negotiate a protocol version with initialize, send notifications/initialized, then discover tools with tools/list.
Use the negotiated MCP-Protocol-Version header on subsequent requests. The example below uses 2025-03-26, exercised by the local compatibility tests.
This deployment is stateless: it does not issue an Mcp-Session-Id. Tool inputs are sent in params.arguments.

Initialize, discover, then call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

Tool calls and results

Send an OAuth access token as Authorization: Bearer <access-token>. A browser login cookie is not a substitute.
Successful tool responses contain JSON serialized in content[0].text. Object results also include structuredContent.
A tool failure may arrive inside an HTTP 200 response with result.isError: true. Inspect the MCP result, not just the HTTP status.
Authentication challenges can appear in WWW-Authenticate or result._meta["mcp/www_authenticate"]. Return the user to the authorization flow.

Tool calls and results

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_my_notebooks",
    "arguments": {
      "limit": 5
    }
  }
}

Limits and connection lifecycle

The API accepts access tokens with a maximum age and lifetime of five minutes (with a small clock tolerance). Token renewal belongs to your OAuth client and configured issuer.
MCP request budgets are 120 per IP per minute and 60 per authenticated identity per minute. Tool responses are limited to 128,000 UTF-8 bytes of serialized result data.
The transport permits 20 in-flight requests per API process. Overload returns 503; exhausted request budgets return 429. Respect Retry-After when present.
The browser connection routes have a separate budget of 20 requests per IP per minute. Manual account-link flows expire after ten minutes.
The route defines no universal tool-execution timeout. Use a bounded client timeout; inspect a timed-out draft/proposal before creating a new one. Reuse the same identifier and identical request when retrying a write.