Document · Krew · 7 min read
Using MCP Servers with Kaptain
Kaptain can connect to external MCP servers and make their tools available through the Krew tool system.
What MCP adds
MCP servers expose external tools. When connected and enabled, those tools join the Krew tool catalog and can be called during a normal run. Kaptain routes calls through its own dispatcher rather than asking a model to operate the external service directly.
Two kinds are supported: a local server, which is a command Kaptain spawns and talks to over stdio, and a remote server, which is a hosted URL Kaptain connects to over streamable-HTTP.
Before connecting
Kaptain does not install every MCP server runtime for you. Install whatever the chosen MCP server requires first: Docker, Node/npx, Python, Go, a local binary, network access, API credentials, or service-specific setup.
Add a server
- Open the Krew view from the activity bar.
- In its sidebar, switch the category from Native Tools to MCP Servers.
- Click + Add server.
- Fill in the fields described below — the command for a local server, or the URL for a remote one.
- Click Add & connect. Kaptain saves the server, starts or connects it, and handshakes for its tool list.
There is one dialog for both kinds of server. You do not choose a transport: filling in a command makes it a local server that Kaptain spawns, and filling in a URL makes it a remote one.
The dialog fields
| Field | What to put in it |
|---|---|
| Name | A lowercase id for the server, e.g. tavily. Its tools appear under this name in the catalog. |
| Local command | The program Kaptain runs: npx, uvx, or a path to a binary. Leave empty for a remote server. |
| Arguments | Space-separated arguments for that command, e.g. -y some-mcp-server. |
| Remote URL | The endpoint of a hosted server, e.g. https://example.com/mcp. Leave empty for a local server. The transport is streamable-HTTP. |
| Env / headers | One KEY=VALUE per line. The same field serves both kinds: for a local server the pairs become environment variables, for a remote one they become request headers, so an API key goes here either way. |
Fill in the command or the URL, not both. Values in this field are stored on the machine and are never echoed back to the browser afterwards — the interface shows only the key names.
Status and removal
Each server appears as a row with a status dot, the command or remote URL, its state, and how many tools it exposes. A server that fails to start shows the error on its own row. Remove stops the server and deletes its entry.
Tools from a connected server join the catalog under Native Tools, where each has its own on/off switch like any built-in tool.
Will Kaptain call MCP tools automatically?
When the MCP server is connected, enabled, and discovered, its tools can be included in the tool set for tool-capable runs. If the active model selects one of those tools, Kaptain calls the MCP server.
You can also ask explicitly, for example: Use the GitHub MCP tool to list open pull requests.
Agent tool scope
An agent can be restricted to a subset of tools. That allowlist lives in the agent's kapsule.json, in its tools list, alongside use_kapsule_tools for granting everything its own MCP service exposes. It is not editable from the Agents view, which covers the agent's model, persona, task, schedule, and on/off state. An agent with no allowlist can use the globally enabled tools.