Skip to main content

Installing MCP Servers

Three sources for an MCP server: a marketplace registry, a manual config entry for a private/local server, or a capability bundle that ships its own. The mechanics are the same — what differs is where the manifest comes from.

1. From the marketplace (easiest)​

The same install action across surfaces:

Settings → Marketplace → Tools. Search, read the description, click Install. A confirmation dialog summarizes the tools the server will provide and any new permissions it requires.

What happens internally — same in every surface:

  1. The marketplace manifest is downloaded and signature-verified.
  2. Codebolt checks compatibility (MCP protocol version, required dependencies).
  3. The server binary or package is fetched.
  4. A local entry is added to your workspace's .codebolt/mcp-servers.yaml.
  5. The server is spawned under PluginProcessManager.
  6. Codebolt performs the MCP handshake and enumerates the tools.
  7. The tools appear in your workspace's tool namespace.

You see a success toast (desktop), a ✓ installed line (CLI), a state-change notification (TUI), or a 200 response (API/SDK) — but the work is the same.

2. Manual configuration (for private or local servers)​

When you have an MCP server that isn't on the marketplace — an internal tool, a development build, a local binary, a remote endpoint — add it manually.

Edit .codebolt/mcp-servers.yaml (create it if it doesn't exist):

servers:
  # Local binary
  my-linter:
    command: /usr/local/bin/my-linter-mcp
    args: ["--config", ".linterrc"]
    env:
      LINTER_MODE: strict

  # Node package
  another-tool:
    command: node
    args: ["./tools/my-mcp-server/index.js"]

  # Python package
  py-tool:
    command: python
    args: ["-m", "my_tool.server"]

  # Remote HTTP
  internal-api:
    url: https://mcp.my-company.com
    auth:
      type: bearer
      token_env: INTERNAL_MCP_TOKEN

Save the file. Codebolt watches the file and starts any new servers automatically.

To verify: Settings → Tools should show the new server within a few seconds, with state running and a list of provided tools.

Field reference​

FieldRequiredMeaning
commandfor localBinary or interpreter to run
argsoptionalArguments to pass
envoptionalEnvironment variables for the server process
cwdoptionalWorking directory (defaults to project root)
urlfor remoteRemote MCP endpoint
authoptionalAuth block for remote servers
auth.typebearer, basic, custom_header
auth.token_envEnv var to read the token from (never hard-code tokens)
startup_timeoutoptionalHow long to wait for the handshake (default 10s)
restart_policyoptionalalways, on_failure, never (default on_failure)

3. As part of a capability bundle​

Capabilities can ship MCP servers. When you install a capability, its MCP servers are installed automatically as part of the bundle.

You see them in Settings → Tools but they're marked as "provided by capability X" — uninstalling them requires uninstalling the capability.

Verifying an install​

After any install:

  1. Settings → Tools — the server should show running.
  2. Expand the server — you should see a list of tools with descriptions.
  3. Test a tool — click any tool and pick "Test". Enter sample arguments. You should get a structured response.

If the server is red (errored), expand the logs:

ERROR: spawn my-linter-mcp ENOENT

→ binary isn't on PATH. Fix the command: to be an absolute path, or add the binary to PATH.

ERROR: handshake timeout

→ the server is running but not speaking MCP. Either the wrong binary, a crashed startup, or a version mismatch.

ERROR: unauthorized (401)

→ remote server rejected auth. Check token_env points at a real env var.

Security considerations​

An MCP server you install runs code on your machine with your credentials. Treat it the same way you'd treat installing a shell tool or an npm package:

  • Check the source. Marketplace entries show author and install count. Low-trust sources warrant extra caution.
  • Read the tools list. A linter that wants codebolt_fs.write_file + codebolt_git.push is suspicious. A linter needs reads, not writes.
  • Prefer first-party servers from the vendor of the service you're integrating. "Stripe's official MCP server" > "some person's Stripe MCP".
  • Use env-var auth for secrets. Never hard-code tokens in mcp-servers.yaml — that file gets committed.
  • Start with a scoped allowlist. Don't immediately add new tool families to every agent's tools.allow. Add them only to agents that need them.

Troubleshooting​

"The server starts, tools appear, but my agent says 'tool not found'"​

The agent's tools.allow doesn't include the new tool. Add it:

# .codebolt/agents/my-agent/agent.yaml
tools:
  allow:
    - codebolt_fs.*
    - my-linter.*    # ← add this

Or use the agent picker to switch to an agent with a broader allowlist.

"The server keeps restarting"​

Check the logs in Settings → Tools → my-server → logs. Usually a crash loop from a missing dependency, a port conflict, or a config error.

"Every new shell has to re-set the env var"​

Put it in your shell profile (.zshrc, .bashrc) or use a secrets manager that your shell loads automatically.

"The server is slow and blocks agents"​

MCP servers can be slow — that's a property of the server, not Codebolt. Agents wait on tool calls. If a server is consistently slow:

  • Check if the server is doing work it doesn't need to (e.g. re-initializing on every call).
  • Look for a faster alternative or build a wrapper that caches results.
  • Constrain which agents use the slow tool.

Uninstalling​

Settings → Tools → Uninstall on the server row. Confirm in the dialog.

The server is stopped, removed from .codebolt/mcp-servers.yaml, and its tools disappear from the namespace. Agents that referenced those tools will get tool_not_found errors on next use — update their allowlists to remove the stale entries.

Uninstalling does not delete historical runs that used the tool; those are still queryable via the event log.

See also​