> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP servers

> Connect Capy to external tools and data through remote HTTP or local stdio Model Context Protocol servers.

## Overview

Model Context Protocol (MCP) servers give Capy access to tools provided by
external services and local processes. Once a server is connected, Captain,
Build, and Review agents can discover and use its tools while working.

Configure MCP servers from **Settings → MCP servers** in a project.

## Add an MCP server

<Steps>
  <Step title="Choose a server">
    Select a server from the marketplace, or click **New MCP server** to add a
    custom server.
  </Step>

  <Step title="Choose its availability">
    Save the server as personal, project, or org-wide. This controls who can see
    and use the server configuration.
  </Step>

  <Step title="Configure the transport">
    For a remote server, enter its full HTTP endpoint. For a local server, enter
    the stdio command, arguments, working directory, and environment variables.
  </Step>

  <Step title="Connect authentication">
    If an HTTP server requires OAuth, open the saved server and click
    **Connect**. Servers that do not require authentication are ready after Capy
    discovers their tools.
  </Step>
</Steps>

Each person can disable a configured server without removing it for everyone
else.

## Availability

| Availability | Who can use it                                    |
| ------------ | ------------------------------------------------- |
| **Personal** | Only you, in the current project                  |
| **Project**  | Everyone with access to the current project       |
| **Org-wide** | Everyone in the organization, across all projects |

Project and org-wide servers can have either personal or shared OAuth
connections:

* **Personal connection** — credentials belong to one Capy user. When both
  personal and shared connections exist, Capy uses the current user’s personal
  connection.
* **Shared connection** — credentials are available to everyone who can use the
  server. Only org admins can connect or disconnect shared credentials.

## Remote HTTP servers

Choose **HTTP** and enter the server’s full MCP endpoint. Capy attempts
Streamable HTTP first and falls back to the legacy SSE transport when the server
does not support Streamable HTTP.

For servers that use a static token or API key, add the required HTTP header.
Store sensitive values in project environment variables and reference the
variable from the header instead of entering a secret directly in the server
configuration.

```text theme={null}
Server key: internal-tools
URL: https://tools.example.com/mcp
Header: Authorization
Value: $INTERNAL_TOOLS_TOKEN
```

## Local stdio servers

Choose **Stdio** for an MCP server that runs as a process inside the agent VM.
Configure its command, arguments, working directory, and environment variables.

```text theme={null}
Server key: local-docs
Command: npx
Arguments: -y, @example/docs-mcp
```

The command and its dependencies must be available in the project’s VM. Add
installation steps to the project’s [Dev environment](/configs/dev-environment)
when needed.

Stdio servers do not use the browser OAuth flow. Provide any required
credentials through environment variables.

## Transport and OAuth support

| Capability                         | Support                                          |
| ---------------------------------- | ------------------------------------------------ |
| Streamable HTTP                    | Supported and preferred for remote servers       |
| SSE                                | Supported as a fallback for older remote servers |
| Stdio                              | Supported inside the agent VM                    |
| MCP OAuth 2025-06-18               | Supported                                        |
| PKCE                               | Supported with `S256`                            |
| Dynamic Client Registration        | Supported                                        |
| OAuth Client ID Metadata Documents | Supported when advertised                        |

For protected HTTP servers, Capy supports the MCP OAuth authorization flow from
the 2025-06-18 specification, including:

* OAuth 2.1 authorization code flow with PKCE
* OAuth Protected Resource Metadata and Authorization Server Metadata discovery
* OAuth resource indicators in authorization and token requests
* Dynamic Client Registration
* Public clients with `token_endpoint_auth_method: none`
* Access-token refresh when the server issues a refresh token

Capy can also use OAuth Client ID Metadata Documents when an authorization
server advertises support.

## OAuth redirect URIs

Authorization servers that enforce a redirect URI allowlist must register the
following callback URI:

```text theme={null}
https://capy.ai/api/mcp/oauth/callback
```

## How agents use MCP tools

Before calling a tool, Capy:

1. Connects to the configured server and lists its available tools.
2. Reads the selected tool’s input schema.
3. Calls the tool with schema-valid arguments.

If a server reports that authentication is required, Capy pauses the affected
action and asks you to connect or reconnect the server.

<Note>
  Connect only servers you trust, and keep API keys or static tokens in project
  environment variables rather than source control.
</Note>