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

# Platform MCP

> Connect AI agents to the CNAP API via the Model Context Protocol

The platform MCP server gives AI agents full programmatic access to CNAP — managing clusters, deploying products, monitoring infrastructure, and automating operations through the same API that powers the dashboard.

```
https://cnap.tech/mcp
```

Authentication uses **OAuth 2.1** with PKCE. MCP clients that support the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) handle this automatically.

<Info>
  This is the **platform** MCP server for managing CNAP resources. For the **documentation** MCP server used to search docs, see [Documentation MCP](/ai/docs-mcp).
</Info>

## Why Code Mode

Most MCP servers register one tool per API endpoint — `list-clusters`, `get-install`, `create-product`, and so on. As the API grows, the tool list explodes, eating context window tokens and requiring constant maintenance.

**Code Mode** (also called **programmatic tool calling**) replaces hundreds of individual tools with just two:

1. **`search`** — discover endpoints by querying the OpenAPI spec
2. **`execute`** — call endpoints by writing JavaScript against a typed API client

The agent writes code to make API calls, chain results, and filter data — all in a single tool invocation. A single `execute` call can fan out dozens of internal API requests in parallel, aggregate results, and return a summary. Less token overhead, fewer round trips, and zero maintenance when the API evolves.

Inspired by [CodeAct](https://machinelearning.apple.com/research/codeact), this works because LLMs are better at writing code than making individual tool calls — they have seen millions of lines of real-world code but only contrived tool-calling examples.

<CardGroup cols={3}>
  <Card title="CodeAct" icon="flask" href="https://machinelearning.apple.com/research/codeact">
    Apple ML research on LLM code generation for tool use
  </Card>

  <Card title="Code Mode" icon="cloud" href="https://blog.cloudflare.com/code-mode/">
    Cloudflare's introduction of the pattern
  </Card>

  <Card title="PTC" icon="message-bot" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling">
    Anthropic's recommended approach
  </Card>
</CardGroup>

CNAP's implementation uses the open-source [`cnap-tech/codemode`](https://github.com/cnap-tech/codemode) library.

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Agent as AI Agent
    participant MCP as CNAP MCP Server
    participant Sandbox as V8 Sandbox
    participant API as CNAP API

    Agent->>MCP: search({ code: "..." })
    MCP->>Sandbox: Execute against OpenAPI spec
    Sandbox-->>Agent: Matching endpoints

    Agent->>MCP: execute({ code: "..." })
    MCP->>Sandbox: Run agent's JavaScript
    Sandbox->>API: cnap.request() (auth injected)
    API-->>Sandbox: Response
    Sandbox-->>Agent: Results
```

## Tools

### `search`

Discover available API endpoints by querying the OpenAPI spec. The agent writes a JavaScript function that receives the full spec as `spec`:

```js theme={null}
// List all endpoints
async () => {
  const results = [];
  for (const [path, methods] of Object.entries(spec.paths)) {
    for (const [method, op] of Object.entries(methods)) {
      results.push({ method: method.toUpperCase(), path, summary: op.summary });
    }
  }
  return results;
}
```

### `execute`

Call API endpoints by writing JavaScript that uses `cnap.request()`. The agent discovers endpoints with `search` first, then calls them:

```js theme={null}
// List all workspaces
async () => {
  const res = await cnap.request({ method: "GET", path: "/v1/workspaces" });
  return res.body;
}
```

```js theme={null}
// Chain calls: find a workspace, then list its clusters
async () => {
  const ws = await cnap.request({ method: "GET", path: "/v1/workspaces" });
  const first = ws.body.data[0];
  const clusters = await cnap.request({
    method: "GET",
    path: "/v1/clusters",
    headers: { "X-Workspace-Id": first.id }
  });
  return { workspace: first.name, clusters: clusters.body.data };
}
```

<Note>
  Authentication is handled automatically — the agent cannot set or read the `Authorization` header. All requests run inside a sandboxed V8 isolate.
</Note>

## Kubernetes Access

The API includes a transparent Kubernetes proxy and a command execution endpoint, giving agents direct access to cluster resources — pod logs, resource listing, API discovery, and running commands.

<Card title="Kubernetes Access Guide" icon="dharmachakra" href="/ai/kubernetes-access">
  Learn how agents use the kube proxy and exec endpoints with full examples
</Card>

## Resources & Prompts

The MCP server also exposes resources and prompts:

| Type     | Name                      | Description                                             |
| -------- | ------------------------- | ------------------------------------------------------- |
| Resource | `cnap://user/profile`     | Current authenticated user info                         |
| Prompt   | `infrastructure-overview` | Analyze clusters, installs, and products in a workspace |
| Prompt   | `deployment-status`       | Check deployment health and identify issues             |

Both prompts accept a `workspaceId` argument.

## Security

<Warning>
  All agent-generated code runs in a **sandboxed V8 isolate** with strict resource limits — there is no access to Node.js APIs, the filesystem, or the network beyond the CNAP API.
</Warning>

* **No auth access** — the sandbox cannot read or set the `Authorization` header; auth is injected server-side
* **Memory limit** — 64 MB per isolate
* **CPU timeout** — 30 seconds
* **Request limit** — 50 API calls per execution
* **Response limit** — 10 MB max response size
* **In-process routing** — requests never leave the server

## Related

<CardGroup cols={2}>
  <Card title="Code Mode in Action" icon="bolt" href="/ai/code-mode-in-action">
    See real examples of agents composing complex operations
  </Card>

  <Card title="Kubernetes Access" icon="dharmachakra" href="/ai/kubernetes-access">
    Kube API proxy, pod logs, and command execution
  </Card>

  <Card title="Documentation MCP" icon="book" href="/ai/docs-mcp">
    Search and query CNAP docs in real-time
  </Card>

  <Card title="Quick Setup" icon="plug" href="/ai/index#quick-setup">
    Configure your AI tool to connect in under a minute
  </Card>
</CardGroup>