Skip to main content
Peel hosts an MCP server at https://api.peel.sh/mcp that speaks JSON-RPC over HTTP POST; every platform tool is a one-to-one wrapper over a REST route, and your endpoints are called through call_endpoint.

Connect a client

Use OAuth when your client supports it, or an API key for a fixed credential. See Authentication.
This works in Claude Code, Cursor, Codex, Claude Desktop and any MCP client that supports remote HTTP servers. If negotiation fails, check the client’s MCP log first: the URL or the auth method is usually wrong. Some clients need their own OAuth callback URI registered; Cursor uses cursor://anysphere.cursor-mcp/oauth/callback.

Use it from an agent

  1. Call list_apis to reuse an API, or create_api with a url and instructions to build one. Pass wait_for_completion: true to wait.
  2. Call get_api with the api_id. Read status, endpoints[].endpoint_name, input_schema and examples before calling anything.
  3. If get_api returns a non-null user_input_prompt, call respond_to_api_input. For a live question (user_input_prompt.live is true) send response: { "question_id": "...", "answer": "..." }.
  4. Call call_endpoint with the api_id, endpoint_name and params.
A tools/call request for call_endpoint:
The reply is a JSON-RPC response whose result is an MCP tool result. result.content holds a text item with the same JSON envelope REST :call returns (status, status_code, data, error_code, execution_time, credits_charged), and result.isError may be set. Protected endpoints take session_id and encryption_key as top-level arguments, next to api_id and endpoint_name, never inside params. See Signed-in and action endpoints.

Platform tools

Each tool maps to one REST route. The scope is the OAuth scope a bearer token needs; API keys are not scoped. Parameters for each tool are in tools/list, and each REST route is in the API Reference. Every tool in tools/list has a title. Every platform tool has an outputSchema, and so does an endpoint tool whose stored output schema strict JSON Schema 2020-12 validators accept; the stored schema describes the result’s data. A schema with a nested $id, a $ref outside #/$defs or #/definitions, or a property named like a built-in object member (such as toString or constructor) gets no outputSchema, and that tool’s results are text only. A successful result from a tool with an outputSchema carries structuredContent that matches it, next to the same JSON as text for older clients. Errors and refusals set isError and come back as text only.

Reaching any read route

When no tool covers what you need, such as the source export or your webhooks, find the route with search_routes, read its parameters with describe_route, and call it with call_read_route:
The result holds the route’s status_code and body, exactly as a direct REST call with your key returns them. The call runs as your API key, so the key’s access, its team role and an API limit refuse it the way they refuse the REST call. It calls GET routes only; changes go through their own tools. It needs an API key: OAuth sign-ins get api_key_required, since the REST API takes only keys. File routes and the long-polling wait route are left out.

Direct JSON-RPC clients

  • Send an Accept header that includes application/json or text/event-stream. Otherwise Peel returns 406.
  • Peel serves the stateless 2026-07-28 revision. Call server/discover, or initialize as older clients do (next item). With server/discover, put the version in each request’s _meta as io.modelcontextprotocol/protocolVersion. If you also send the MCP-Protocol-Version, Mcp-Method or Mcp-Name headers, they must match the body. Discovery results and the keyless tools/list may be cached for an hour (cacheScope: "public"). The tools/list of /mcp and of each API’s server depends on your key, so it is cacheScope: "private" with a one-minute ttlMs.
  • Clients that initialize can negotiate 2025-11-25, 2025-06-18, 2025-03-26 or 2024-11-05. A request without a protocol-version header is treated as 2025-03-26.
  • Send one JSON-RPC request or notification per POST. Batches are accepted only under 2025-03-26.
  • A body that is not JSON answers -32700 Parse error with HTTP 400. JSON that is not a request object or a batch array, such as a string, number, true or null, answers -32600 Invalid Request with HTTP 200.
  • tools/list on /mcp pages with nextCursor. Send it back unchanged: a cursor that is altered, empty or from another key answers -32602 Invalid params. The keyless and per-API servers list every tool on one page, so any cursor there answers -32602.
  • GET /mcp and DELETE /mcp return 405.
OAuth clients can register with a Client ID Metadata Document (a client_id that is an HTTPS URL to the client’s metadata, as ChatGPT uses) or with dynamic client registration. Authorization responses include iss.

One MCP server per API

Each API also has its own MCP server at https://api.peel.sh/mcp/apis/{api_id}. Its tools are that API’s endpoints and nothing else, so an agent that only needs one integration sees a short tool list. export_mcp returns the URL as connect.url. It accepts the same OAuth tokens and API keys as /mcp.

Without an account

https://api.peel.sh/mcp/keyless takes no key and offers only the marketplace tools, for public data calls under the same daily limits as REST. See Call without an account.

Long builds as tasks

Builds take minutes. Clients that declare the MCP Tasks extension (io.modelcontextprotocol/tasks) get a task back from create_api, revise_api and rebuild_api instead of waiting:
  • tasks/get reports working, then completed with the API, or input_required when the build asks a question.
  • A question arrives as an elicitation. Plain questions are forms; answer them with tasks/update. Secret questions, such as a texted code, are URL elicitations that open the API’s page on Peel, so the code never passes through the agent.
  • tasks/cancel acknowledges cancellation.
Clients without the extension get the build object and poll get_api. Webhooks give servers the same progress.

Errors

Tool-level failures such as 404 Endpoint not found or an error_code use the same shapes as REST. See Errors.