This is the platform MCP server for managing Akua resources from external
AI tools. Start with 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, use Hosted 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:
search: discover endpoints by querying the OpenAPI specexecute: call endpoints by writing JavaScript against a typed API client
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, 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.
CodeAct
Apple ML research on LLM code generation for tool use
Code Mode
Cloudflare’s introduction of the pattern
PTC
Anthropic’s recommended approach
akua-dev/codemode library.
How it works
Tools
search
Discover available API endpoints by querying the OpenAPI spec. The agent writes a JavaScript function that receives the full spec as spec:
execute
Call API endpoints by writing JavaScript that uses platform.request(). The agent discovers endpoints with search first, then calls them:
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 returns404 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.Kubernetes Access Guide
Learn how agents use the kube proxy and exec endpoints with full examples
Resources and prompts
The MCP server also exposes resources and prompts:
Both prompts accept a
workspaceId argument.
Security
- No auth access: the sandbox cannot read or set the
Authorizationheader; 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
Agent setup
Start with the CLI and add platform MCP when useful.
Code Mode in action
See real examples of agents composing complex operations.
Kubernetes access
Kube API proxy, pod logs, and command execution.
Documentation MCP
Search and query Akua docs in real-time.