Coding agents
Set up a coding agent such as Claude Code, Codex or Cursor to manage Kapten, with the Kapten agent skill and the CLI's local MCP server.
A coding agent works with Kapten through three pieces:
- the
kaptenskill, which teaches it the resource model and how to run the CLI: discover commands from help, confirm the organization before changing anything, verify the result; - the
kaptenMCP server,kapten mcp serve, which gives it the CLI’s operations as tools; - the
kapten-docsMCP server,https://docs.kapten.io/mcp, which searches and reads these docs.
Set up an agent with the CLI
kapten skills install writes the skill of your CLI version where your agents read skills, and with --mcp adds both MCP servers to their configuration:
kapten --context work skills install --mcp # this project, every agent on this machine
kapten skills install --global --mcp --agent codex # for your user, one agent
It knows Claude Code, Codex, Cursor, OpenCode and GitHub Copilot, leaves the other entries of their configuration untouched, and updates its own when run again. See kapten skills.
Install the plugin
The kapten-io/skills repository is a plugin with both skills (kapten and kapten-docs) and both MCP servers, for agents that install plugins. Each CLI release publishes it, tagged with the release’s version. Its kapten server runs the CLI with npx, so it needs Node.js and a login.
# Claude Code
/plugin marketplace add kapten-io/skills
/plugin install kapten@kapten
Codex, Cursor and other clients of the Agent Plugins standard install it from the same repository. For the skills alone, in any agent: npx skills add kapten-io/skills. These docs also list the skills at /.well-known/agent-skills/index.json.
Configure an MCP client by hand
kapten mcp serve runs an MCP server over stdio: a coding agent that supports MCP can then list, create, update and delete Kapten resources with the same operations as the CLI’s commands. The server runs on your machine, with the CLI’s login. It has no network listener.
Log in
kapten login --name workThe server uses a saved context, or an OAuth application from the environment variables.
Add the server to your client
Most MCP clients take a configuration like this one. It runs the CLI with npx, which needs Node.js:
{
"mcpServers": {
"kapten": {
"command": "npx",
"args": ["-y", "@kapten/cli@latest", "--context", "work", "mcp", "serve"]
}
}
}One organization per server
The server picks its context when it starts and keeps it: kapten auth use does not change a running server. Name the context with --context, as above, so the server does not depend on the active one. To work with several organizations, add one server per context, each with its own name.
Limit what the agent can do
The server exposes every operation the CLI has, including deletes. Delete tools are marked destructive, so clients that ask before running such tools ask for them. The agent can do what your login can do: for a narrower access, run the server as an OAuth application with only the Roles it needs.
--operations limits the tools to a list of operation IDs, the operationId of each operation in the Platform API reference:
"args": ["--context", "work", "mcp", "serve", "--operations", "listProjects,listEnvironments,queryApplicationRunLogs"]
--request-timeout bounds each API request, in seconds (30 by default), and --max-result-bytes the size of a tool’s result (1 MiB by default). See kapten mcp serve.