---
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. The directory section lists featured integrations and the ten most popular directory entries, and search returns up to 20 matches. When the project's connected GitHub repositories use a recognized SDK or marker file, such as `@sentry/node` or `wrangler.toml`, matching integrations appear first with the reason they were suggested. Integrations already installed are left out.
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.

### OAuth token refresh

After you connect, Hoplite keeps the OAuth connection alive on its own. Agents refresh the access token shortly before it expires, and again if the server rejects it, then save the new tokens, including a rotated refresh token, back to the server's entry. You don't need to reconnect when an access token expires, and concurrent threads using the same server share the latest tokens.

If the provider rejects the refresh token (for example, the grant was revoked, or it expired after a long idle period), the server row shows **Reconnect required**. Agent runs continue without that server's tools and tell you it needs reconnecting. Select **Connect** on the row to sign in again. Tokens are shared by the whole organization or project, not stored per user.

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

Sitemap discovery is not enabled for this deployment.