---
title: "MCP servers"
description: "Connect external tools and services directly to your Hoplite agents through MCP."
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: Connect external tools and services directly to your Hoplite agents through MCP.
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

Use a remote server configuration such as:

```json title=".hoplite/settings.json (excerpt)"
{
  "mcpServers": [
    {
      "name": "docs-search",
      "enabled": true,
      "config": {
        "transport": "http",
        "url": "https://mcp.example.com/mcp"
      }
    }
  ]
}
```

## Connect an authenticated server

As a team workspace owner or admin:

1. Open **Settings → Project → MCP**, select **Add server**, and choose a catalog server or enter its name and remote URL.
2. Select **Analyze connection** when prompted. Hoplite checks which authentication methods the endpoint supports.
3. For OAuth, choose **Save OAuth connection**, then **Connect** on the server row and complete the provider's sign-in. Saving the entry alone leaves it waiting for credentials.
4. For an API key or bearer token, select that authentication method and enter the credential. If the provider requires a custom header, enter it under **Advanced → Custom headers** as a JSON object, then select **Add server**.
5. Ensure the server is enabled and its row no longer says **needs credentials**. Start a thread and check that the server's tools can be discovered and called. A saved URL alone does not verify authentication or tool access.

If OAuth is unavailable, use the provider's documented token or header method. Keep these credentials in the app's managed configuration, outside the repository file.

## Transports

| Transport | Required fields | Notes |
| --- | --- | --- |
| `http` (default) | `url` | Streamable HTTP; `http(s)` URLs only |
| `sse` | `url` | Server-sent events; `http(s)` URLs only |
| `stdio` | — | Excluded from the hosted agent tool catalog |

<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. Hosted runs do not expose local `stdio` MCP servers. Use a supported remote endpoint to add model-facing tools.
</Callout>

## Configuration precedence

Stored server configuration takes precedence over a repository entry with the same normalized name. Project-scoped stored entries take precedence over organization-scoped entries. A disabled stored entry can therefore suppress a repository entry.

Repository-defined `env` values are removed when merging MCP configuration. Keep credentials in the managed configuration rather than committing them to the repository.

## Credentials

Owners and admins manage stored MCP credentials. Secret values are encrypted individually at rest, masked in API responses, and excluded from realtime sync. Each value is limited to 4,096 bytes. See [Security](/docs/workspace/security#mcp-credentials) for the access boundary.

## 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).