Register the Akka MCP server

The Akka CLI ships an MCP server that exposes Akka’s build, test, deploy, spec-driven-development, and runtime-inspection tools to any MCP-capable AI coding harness. If your harness has a first-class Akka install (see harness support matrix), that install registers the server for you.

Use this page for harnesses whose MCP config is not a project file the Akka CLI can write. akka specify init --agent <name> writes AGENTS.md for AGENTS.md-native harnesses (Warp, Jules, Zed, Copilot coding agent, Codex) but leaves MCP registration to you — the register step below completes the setup. Also applies to any harness with no CLI profile at all (Aider, Sourcegraph Cody, Claude.ai chat).
Prerequisites

  • The Akka CLI on PATH (Install the Akka CLI).

  • An AGENTS.md file at the project root — akka specify init (with no --agent flag) writes one.

Every snippet below registers the same command: akka mcp serve running on stdio, with no extra environment. If a config file at the target path already exists, merge the Akka entry into the existing mcpServers (or equivalent) object rather than overwriting.

Zed

Add to .zed/settings.json at the project root, under context_servers:

{
  "context_servers": {
    "akka": {
      "command": "akka",
      "args": ["mcp", "serve"]
    }
  }
}

Reload Zed’s AI panel after saving. The Akka tools appear under the akka server. Zed also reads AGENTS.md if present, so keeping the file at the project root gives the model Akka conventions in addition to the tools.

OpenAI Codex CLI

Codex reads MCP servers from [mcp_servers.<name>] TOML sections in ~/.codex/config.toml (user-global) or, for trusted projects, .codex/config.toml at the project root.

Recommended: register through the Codex CLI, which writes the config without TOML syntax risk:

codex mcp add akka -- akka mcp serve

Or hand-edit ~/.codex/config.toml (or .codex/config.toml for a trusted project) and add:

[mcp_servers.akka]
command = "akka"
args = ["mcp", "serve"]

Codex reads AGENTS.md natively, so keeping the file at the project root gives the model Akka conventions alongside the tools. akka specify init --agent codex writes an AGENTS.md and prints the same registration hint above.

Aider

Aider does not have native MCP client support. Two workarounds:

  • Drive the Akka CLI directly through Aider’s shell integration — Aider can run akka commands and read their output.

  • Run an MCP-to-stdio bridge alongside Aider and expose akka mcp serve through Aider’s tool interface.

Either way, keep AGENTS.md at the project root so Aider’s model receives Akka conventions.

Sourcegraph Cody

Cody registers MCP servers through its own configuration surface; the exact settings path has moved between Cody releases, so consult the current Cody MCP documentation for the file location that matches your Cody version. The registration entry follows the common stdio pattern:

{
  "mcpServers": {
    "akka": {
      "command": "akka",
      "args": ["mcp", "serve"]
    }
  }
}

Restart the Cody panel after saving.

Claude.ai chat (Projects)

MCP is admin-gated in Anthropic’s Projects surface, so a per-project registration is not possible today. Paste the Akka install playbook from akka.ai into the project’s custom instructions and drive Akka manually through the CLI in a separate terminal.

Generic stdio harness

Any harness that speaks the MCP stdio transport registers a server that runs akka mcp serve with no arguments and no extra environment. The command follows this shape:

{
  "mcpServers": {
    "akka": {
      "command": "akka",
      "args": ["mcp", "serve"]
    }
  }
}

Consult your harness documentation for the exact settings file and key name. Once the harness reloads, the Akka MCP tools are available; the tool inventory is described in akka mcp serve.

See also