---
title: "MCP servers"
description: "Extend the agent's tool catalog with Model Context Protocol servers"
canonical_url: "https://hoplite.sh/docs/agent/mcp"
markdown_url: "https://hoplite.sh/docs/agent/mcp.md"
---

# MCP servers
URL: /docs/agent/mcp
LLM index: /llms.txt
Description: Extend the agent's tool catalog with Model Context Protocol servers
Related: /docs/agent/tools, /docs/sandboxes/scripts, /docs/cli/mcp-server, /docs/cli

# MCP servers

Attach [Model Context Protocol](https://modelcontextprotocol.io) servers to a project and their tools join the agent's catalog alongside the [first-party tools](/docs/agent/tools).

<Callout type="info" title="Looking for the other direction?">
This page is about giving the Hoplite agent extra tools. To drive Hoplite from Claude Code, Cursor, or another MCP client, see [Hoplite's own MCP server](/docs/cli/mcp-server).
</Callout>

## Two ways to configure

- **In the app** — under **Settings → Project → MCP**, add servers to the MCP section
- **In the repo** — the `mcpServers` array in [`.hoplite/settings.json`](/docs/sandboxes/scripts), so the config ships with the code

Both accept the same shape:

```json title=".hoplite/settings.json (excerpt)"
{
  "mcpServers": [
    {
      "name": "docs-search",
      "enabled": true,
      "config": {
        "transport": "http",
        "url": "https://mcp.example.com/mcp"
      }
    },
    {
      "name": "local-tooling",
      "enabled": true,
      "config": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@example/mcp-server"]
      }
    }
  ]
}
```

## Transports

| Transport | Required fields | Notes |
| --- | --- | --- |
| `http` (default) | `url` | Streamable HTTP; `http(s)` URLs only |
| `sse` | `url` | Server-sent events; `http(s)` URLs only |
| `stdio` | `command` | Optional `args`, `cwd`, `env`; runs inside the sandbox |

<Callout type="warning" title="URL restrictions">
Remote (`http`/`sse`) server URLs may not point at loopback, link-local, private, or internal hosts — this guards against server-side request forgery. To talk to something running inside the sandbox, use a `stdio` server instead.
</Callout>

## Credentials and encryption

Auth headers and OAuth tokens you give a server are treated as secrets end to end.

- **Encrypted individually at rest.** Every secret value — each header, each `env` value, values under sensitive key names, secret-bearing URLs — is encrypted on its own with [AWS KMS](https://aws.amazon.com/kms/) under a customer-managed key that has automatic rotation enabled. There is no shared data key whose compromise would expose everything.
- **Auditable decryption.** Each KMS call carries an encryption context naming the application and the secret's purpose. The context is cryptographically bound into the ciphertext and recorded in AWS CloudTrail, and only the API and agent workers hold IAM permission to use the key.
- **Never returned to a client.** Every API response masks secret values as `********` — including the response to the request that created the server. MCP configurations are also excluded from Hoplite's realtime sync, so the web app never receives them. Values are never written to logs.
- **Decrypted in one place only:** the worker assembling an agent run, at the moment it connects to the server.
- **Changes are role-gated.** Creating, editing, or deleting a server requires a fresh owner or admin check on the org, so a session whose role was revoked is rejected.
- A single value is capped at 4,096 bytes of plaintext (the AWS KMS limit for direct encryption); anything larger is rejected rather than stored unencrypted.

## Importing credentials from the CLI

[`hoplite onboard`](/docs/cli) imports MCP **server addresses only** by default — auth headers stay on your machine, and those servers arrive disabled and marked **needs credentials**.

A separate, explicitly labelled step offers to import the auth state itself: API-key headers from your local config, and OAuth tokens (including refresh tokens) from the stores Claude Code and OpenCode keep them in. Nothing there is selected by default, and nothing is uploaded until you confirm the import. Codex keeps its per-server OAuth tokens in a way that would raise a macOS permission prompt to read, so the CLI does not read them — add those credentials in the app instead.

<Callout type="warning" title="Imported tokens keep their power">
An imported OAuth token or API key grants Hoplite's agents the same access it granted your local tools. Import only what you want agents to use, and rotate upstream if you change your mind — Hoplite cannot show you a value again after saving.
</Callout>

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).