Skip to main content
Version: v2.0

Add an MCP server

An MCP server gives your agent tools it can call. Connect one over HTTP and keep its key in an Agenta project secret. To learn how MCP compares with built-in integrations, see Tools and integrations.

Before you start​

Have these ready:

  • The server's HTTP URL, such as https://example.com/mcp. Agenta supports HTTP connections, but not local processes over stdio.
  • The authentication header and key, if the server requires them. Check the server's documentation for the header name, such as x-api-key.
  • An agent on the Claude Code harness. MCP servers are available on Claude Code. If the agent runs on Pi, the MCP servers section does not appear in its configuration. See Choose a harness and model.

Store the key as a project secret first​

Skip this if the server needs no authentication.

The MCP form does not store the key directly. It references a project secret that Agenta resolves when the agent runs.

  1. Go to Settings in the sidebar, then Secrets.
  2. Click + Create and save the key.

Add the server​

  1. In the playground, set Playground mode to Build.
  2. In the Configuration column, find MCP servers, between Tools and Skills. Its summary reads None when the agent has no MCP servers yet.
  3. Click the + button on that row, labelled Add MCP server.
  4. Fill in the fields below, then click Create.
  5. Click Commit in the Configuration header to make the server part of a version.
FieldWhat to enter
Server nameLetters, numbers, dots, hyphens, or underscores, up to 128 characters, such as exa. The server's tools are labelled with this name.
MCP URLThe server's HTTP endpoint, such as https://example.com/mcp.
AuthenticationNone when the server is open. Secret header when it needs a key in a request header. OAuth is listed but not available yet.
Header nameShown for Secret header. The header the server requires, such as x-api-key.
Project secretShown for Secret header. Pick the secret you created. The list reads No project secrets found when the project has none, so go back and create one in Settings > Secrets.

The server's actions become tools​

The server's actions appear as tools labelled with the server name. When the agent calls one, it appears in the conversation and on any approval card.

note

The agent's Policy in the Advanced dialog governs MCP tools. They do not support per-tool Permission or Auto-approve. Under the default Allow reads policy, every MCP call asks for approval. To run MCP tools without approval, including on a schedule, set Policy to Allow all. See Control what an agent can do.

Next​