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://akua.dev/mcp

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. 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 cnap-tech/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:

// 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:

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

// 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: { "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.

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:

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

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

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.

Hosted agents

The embedded dashboard agent and full agent product model.