> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Platform MCP
> Connect AI agents to the Akua API via the Model Context Protocol
The platform MCP server gives AI agents full programmatic access to Akua: managing clusters, deploying products, monitoring infrastructure, and automating operations through the same API that powers the dashboard.
```
https://mcp.akua.dev
```
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.
This is the **platform** MCP server for managing Akua resources from external
AI tools. Start with [Agent Setup](/agent-setup) when you want a coding agent
to authenticate and operate through the CLI. Add this server later when an
additional OAuth-based tool surface helps. If you want the managed dashboard
experience instead, check [Hosted-agent availability](/agents).
## 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 only 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.
Apple ML research on LLM code generation for tool use
Cloudflare's introduction of the pattern
Anthropic's recommended approach
Akua's implementation uses the open-source [`akua-dev/codemode`](https://github.com/akua-dev/codemode) library.
## How it works
```mermaid theme={null}
sequenceDiagram
participant Agent as AI Agent
participant MCP as Akua MCP Server
participant Sandbox as V8 Sandbox
participant API as Akua 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: platform.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 `platform.request()`. The agent discovers endpoints with `search` first, then calls them:
```js theme={null}
// List all workspaces
async () => {
const res = await platform.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 platform.request({ method: "GET", path: "/v1/workspaces" });
const first = ws.body.data[0];
const clusters = await platform.request({
method: "GET",
path: "/v1/clusters",
headers: { "Akua-Context": first.id }
});
return { workspace: first.name, clusters: clusters.body.data };
}
```
Authentication is handled automatically. The agent cannot set or read the `Authorization` header. All requests run inside a sandboxed V8 isolate.
## Connection troubleshooting
After an OAuth access-token refresh, you can resume a retained MCP session with the rotated bearer token while the session remains valid. MCP sessions are retained for up to 24 hours from initialization and close automatically when they expire. The server accepts a retained session only when the authenticated user, OAuth client, issuer, signed-in OAuth session, authorization grant (including its approved scopes and resource), and workspace context still match, and when any configured client scopes still cover the token's scopes. If a request includes an MCP session ID that the server no longer recognizes, a valid bearer token returns `404` with an invalid or expired session error, so start a new session. Missing or invalid credentials for that request return `401` before the server reveals whether the session exists. Don't retry a retained session ID with different credentials, authorization, or context.
## 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.
Learn how agents use the kube proxy and exec endpoints with full examples
## Resources and prompts
The MCP server also exposes resources and prompts:
| Type | Name | Description |
| - | - | - |
| Resource | `akua://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
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 Akua API.
* **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 topics
Start with the CLI and add platform MCP when useful.
See real examples of agents composing complex operations.
Kube API proxy, pod logs, and command execution.
Search and query Akua docs in real-time.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.