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, the capy agent (threads and their tasks) can discover and use its tools while working. The review agent runs a fixed tool set and never sees MCP tools. Configure MCP servers from Settings → MCP servers in a project.

​
Add an MCP server

1

Create a server

Click New MCP server and give it a short key, like internal-tools.
2

Choose its availability

Save the server org-wide or narrowed to one project. This controls which threads see the server.
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

A server can carry either or both credential kinds:
  • 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 speaks every published MCP protocol revision: it probes with the modern protocol first, and if the server answers as an older one, it falls back through the legacy handshake down to the original HTTP+SSE transport. You don’t configure the revision; Capy detects it per server and caches the answer. For servers that use a static token or API key, add the required HTTP header and paste the value itself. Header values are sealed at rest like any other Capy credential and sent only to that server. They are not interpolated, so an environment-variable reference like $MY_TOKEN would be sent literally and fail authentication.

​
Local stdio servers

Choose Stdio for an MCP server that runs as a process on the thread’s machine. Configure its command, arguments, working directory, and environment variables.
The command and its dependencies must be available on the project’s machines. 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

MCP tools surface to the agent through its tool search, named {server}__{tool}: a server keyed internal-tools with a query_db tool appears as internal-tools__query_db. Only the capy agent gets them; review threads never do. 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, the affected call fails with a message telling the agent an admin must connect the server, and the thread’s failure card links to settings with the server preselected.
Connect only servers you trust, and keep API keys or static tokens in project environment variables rather than source control.