---
title: Coding agents
description: 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 **`kapten` skill**, 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 **`kapten` MCP server**, `kapten mcp serve`, which gives it the CLI's operations as tools;
- the **`kapten-docs` MCP 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:

```bash
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`](/cli/reference/skills).

## Install the plugin

The [kapten-io/skills](https://github.com/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.

```bash
# Claude Code
/plugin marketplace add kapten-io/skills
/plugin install kapten@kapten
```

Codex, Cursor and other clients of the [Agent Plugins](https://agent-plugins.org) 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`](https://docs.kapten.io/.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.

1. **Log in**

    ```bash
    kapten login --name work
    ```

    The server uses a saved context, or an OAuth application from the [environment variables](/cli/authentication#run-in-ci).

2. **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:

    ```json
    {
      "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](/cli/authentication#run-in-ci) 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](/api/platform) reference:

```json
"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`](/cli/reference/mcp).
