> ## 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 configure docs context, platform access, and a read-only workspace briefing prompt. If you want the managed dashboard experience instead, use [Hosted Agents](/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 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.
Hosted Agents use the same idea when a dashboard conversation only needs structured platform work. A user can ask "deploy this repository" in the sidebar, and the agent can search the API, call the right endpoints, render approval prompts, and show progress without starting a retained runtime. If the task needs files, git, package managers, or tests, the agent can move into a retained runtime while keeping the same conversation.
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 the retained MCP session with the rotated bearer token. The server accepts the 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. Start a new session after a `401` authentication error, an invalid or expired session error, or a workspace-context change. 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
Configure docs and platform MCP for coding agents.
See real examples of agents composing complex operations.
Kube API proxy, pod logs, and command execution.
Search and query Akua docs in real-time.