> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peel.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Use your compiled APIs from any MCP-compatible agent.

Peel hosts an MCP server at `https://api.peel.sh/mcp`. Use `call_endpoint` to run the same compiled endpoints you call over REST with the same `api_id`, endpoint names, and schemas. Peel may also expose useful endpoints as dedicated discoverable tools, while generic helper endpoints stay behind `call_endpoint`.

## Quick setup via CLI

The fastest way to connect your agents:

```bash theme={null}
peel setup
```

This authenticates you, auto-detects installed agents, installs the hosted MCP server config, and can optionally install the Peel coding-agent skill on supported clients. No manual JSON editing is needed for the common path.

Detected MCP targets today:

* Claude Code
* Codex CLI
* Cursor
* Claude Desktop

To install for a specific agent only:

```bash theme={null}
peel mcp add --target claude-code
peel mcp add --target cursor
peel mcp add --target codex
```

To remove a previously installed target:

```bash theme={null}
peel mcp remove --target codex
```

If you only want auth without changing MCP config, use `peel auth login` instead. If you want the full health check after setup, keep using `peel setup` because it runs `peel doctor` at the end.

## Manual config

If you prefer manual setup, pick the auth method your client supports and use one of these config blocks:

<Tabs>
  <Tab title="OAuth">
    ```json theme={null}
    {
      "mcpServers": {
        "peel": {
          "url": "https://api.peel.sh/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="API key">
    ```json theme={null}
    {
      "mcpServers": {
        "peel": {
          "url": "https://api.peel.sh/mcp",
          "headers": {
            "X-API-Key": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Use OAuth when your client supports it. Use `X-API-Key` for a fixed credential.

If negotiation fails, check the client-side MCP logs first. The URL or auth method is usually wrong before anything on Peel's side is. Your client may require a client-specific OAuth callback URI. For example, Cursor registers `cursor://anysphere.cursor-mcp/oauth/callback`. Check the client's MCP setup docs for the exact value.

## Direct JSON-RPC clients

Clients that call `POST /mcp` directly must send an `Accept` header that includes `application/json` or `text/event-stream`. Send `MCP-Protocol-Version: 2025-11-25` after initialization when your client supports the current protocol. Peel also accepts `2025-03-26` for older clients, and treats a missing protocol-version header as `2025-03-26` for backward compatibility.

Batch JSON-RPC payloads are only accepted with `MCP-Protocol-Version: 2025-03-26`. Current-protocol requests must send one JSON-RPC request or notification per POST.

## Use the API through an agent

Once connected, the agent sees Peel's platform tools alongside any useful endpoint tools Peel exposes directly. The runtime flow mirrors REST:

<Steps>
  <Step title="Find or create an API">
    Call `list_apis` to reuse an existing one, or `create_api` to compile a new API from a URL. Pass `wait_for_completion: true` if you want the build to block until terminal state.
  </Step>

  <Step title="Inspect the contract">
    Call `get_api` to read `status`, `endpoints`, `auth_mode`, and `requires_session` before running anything. Each endpoint includes `endpoint_type`, `auth_requirement`, `runtime_policy`, `runtime_verification`, schemas, and call examples.
  </Step>

  <Step title="Handle paused builds">
    If `status` is `needs_input`, send the requested object through `respond_to_api_input`. See [API updates](/features/api-updates).
  </Step>

  <Step title="Execute a runtime call">
    Use `call_endpoint` with the `api_id`, `endpoint_name`, and `params` you would use over REST.
  </Step>
</Steps>

`call_endpoint` is the generic runtime path. It works even for endpoints that are not exposed as separate MCP tools.

`call_endpoint` returns the same sanitized response envelope as REST `:call`: `status`, `status_code`, `data`, `error`, `error_code`, `execution_time`, and optional transport, session, and clipped `raw_output` fields. API identity and auth capability fields stay on `get_api` and export metadata rather than inside each runtime response.

## Platform tools reference

Each platform tool is a one-to-one wrapper around a REST route. If you know the REST call you want, the table below shows the equivalent MCP tool, and vice versa.

| MCP tool               | REST route                                              | OAuth scope |
| ---------------------- | ------------------------------------------------------- | ----------- |
| `list_apis`            | `GET /v1/apis`                                          | `mcp:read`  |
| `get_api`              | `GET /v1/apis/{api_id}`                                 | `mcp:read`  |
| `get_api_health`       | `GET /v1/apis/{api_id}/health`                          | `mcp:read`  |
| `export_openapi`       | `GET /v1/apis/{api_id}/exports/openapi`                 | `mcp:read`  |
| `export_mcp`           | `GET /v1/apis/{api_id}/exports/mcp`                     | `mcp:read`  |
| `create_api`           | `POST /v1/apis`                                         | `mcp:write` |
| `revise_api`           | `POST /v1/apis/{api_id}/revise`                         | `mcp:write` |
| `rebuild_api`          | `POST /v1/apis/{api_id}/rebuild`                        | `mcp:write` |
| `respond_to_api_input` | `POST /v1/apis/{api_id}/respond`                        | `mcp:write` |
| `call_endpoint`        | `POST /v1/apis/{api_id}/endpoints/{endpoint_name}:call` | `mcp:tools` |
| `get_credits`          | `GET /account/credits`                                  | `mcp:read`  |

Anything outside this list is not part of the public platform MCP contract. The hosted MCP server is a transport over the same `/v1/apis`, `:call`, export, and credits surfaces rather than a separate runtime.

`get_api_health` returns the same build-stage `failure` diagnostics as `GET /v1/apis/{api_id}/health`, so MCP clients can inspect non-publishable builds without switching to REST.

## Session-backed APIs

When an API requires a target-site session, the login endpoint returns `session_id` and `encryption_key`. Pass both as top-level `call_endpoint` arguments alongside `api_id` and `endpoint_name`, not inside `params`. See [Authenticated APIs](/features/authenticated-apis#mcp-shape) for the full JSON-RPC envelope.

<Warning>
  `respond_to_api_input` is for paused **build** state (`needs_input`). It is not a runtime substitute for login or interactive browsing.
</Warning>

## Related pages

* [Authentication](/getting-started/authentication): host auth and target-site sessions
* [Deterministic runtime](/concepts/deterministic-runtime): what the runtime contract is and is not
* [API updates](/features/api-updates): revise, rebuild, and respond
* [Errors](/reference/errors): runtime error codes