Skip to main content
An AI agent passes an OAuth 2.1 boundary to reach just two tools — search and execute — which run inside a sealed V8 sandbox with no filesystem or network access; its only exit is the platform API with authentication injected server-side
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.
Authentication uses OAuth 2.1 with PKCE. MCP clients that support the MCP authorization spec handle this automatically.
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 configure docs context, platform access, and a read-only workspace briefing prompt. 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 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, 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’s implementation uses the open-source akua-dev/codemode library.

How it works

Tools

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 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.

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

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

Agent setup

Configure docs and platform MCP for coding agents.

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.