Skip to main content

​
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

1

Choose a server

Select a server from the marketplace, or click New MCP server to add a custom server.
2

Choose its availability

Save the server as personal, project, or org-wide. This controls who can see and use the server configuration.
3

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.
4

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.
Each person can disable a configured server without removing it for everyone else.

​
Availability

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.

​
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.
The command and its dependencies must be available in the project’s VM. Add installation steps to the project’s Dev environment when needed. Stdio servers do not use the browser OAuth flow. Provide any required credentials through environment variables.

​
Transport and OAuth support

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:

​
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.
Connect only servers you trust, and keep API keys or static tokens in project environment variables rather than source control.