Skip to main content

Add an MCP Tool

Adding a remote (MCP) tool to an agent is a two-step process:

  1. Declare the tool on the agent (URL + auth method) — done in the agent editor.
  2. Configure it on the Tool Configuration page — authorize, fetch the tool list, enable what you need.

Skip step 2 and the agent won't be able to call the tool.

What you need​

  • An agent already created (or you can add a tool while creating a new one).
  • The MCP server URL.
  • For OAuth: whether the server supports OAuth Dynamic Client Registration ("Automatic") or requires a pre-registered client ID ("Static").
note

API-key authentication for MCP tools is not enabled today. The dropdown shows API Key as an option but it is currently disabled. If your MCP server only supports an API key, run it behind an OAuth-aware proxy or wait for first-class API-key support.

Finding MCP servers​

In the agent editor's Tool Integration section, click the ? icon button beside the + button. This opens the More Tools dialog with links to:

  • Claude Documentation — remote MCP server list
  • mcpservers.org/remote-mcp-servers — curated MCP catalog

Step 1 — declare the tool on the agent​

  1. Open the agent in the editor (or create a new one).
  2. In the Tool Integration section, click the + button:
    • Pre-defined Tool — pick from your saved tool templates.
    • From Scratch — fill in a blank form.
  3. Fill in:
    • Name — a label for this tool integration.
    • URL — the MCP server endpoint.
    • Auth — OAuth 2 or none. (API Key is shown but currently disabled.)
    • For OAuth 2: pick:
      • Automatic (Dynamic Client Registration / CIMD) — if the server supports OAuth DCR.
      • Static (Pre-registered client) — if you've registered an OAuth client manually. Provide the Client ID; some servers also need a Client Secret.
    • Timeout — optional, in seconds.
  4. Save the tool entry (✓ button on the row).
  5. Click Update Agent (or Create Agent for new agents) at the bottom.

The tool is now declared but not yet usable — proceed to Step 2.

Step 2 — configure on the Tool Configuration page​

  1. Go back to Your AI Agents.
  2. On the agent's card → click View more → Configure Tools (wrench icon).
  3. You are now on the Tool Configuration page (/tool-config).

If it's OAuth​

Click Configure on the tool entry.

  • Automatic OAuth: you are redirected to the provider's consent screen. After approving, you are returned to the dashboard and the encrypted token is saved.
  • Static OAuth: you may need to enter the Client ID first, then click Configure to start the redirect.

If it's no auth​

Skip straight to fetching.

Fetch and pick tools​

After authorization (or immediately for no-auth tools):

  1. Fetch the tool list from the server. The dashboard calls the MCP server's discovery endpoint and lists every tool it exposes.
  2. Each discovered tool has an enable/disable toggle.
    • Enabled — the agent can use this tool.
    • Disabled — hidden from the LLM.
  3. Enable only what the agent actually needs. Fewer tools = more accurate tool selection by the LLM.
  4. Click Save.

Test it​

Open a chat with the agent. Ask a question that should trigger the tool. If the agent doesn't call it, check Troubleshooting below.

Re-fetching when the server changes​

If the MCP server adds new tools later, click the Reload agent data (fetch latest KB list and tools) button at the top of the Tool Configuration page. New tools appear with switches off by default — enable the ones you want and save again.

Removing a tool​

In the agent editor → Tool Integration → click the delete icon on the tool row → Update Agent. Any stored OAuth token for that tool is invalidated.

Troubleshooting​

SymptomLikely cause
Configure button does nothingServer expects Static OAuth and you haven't entered the Client ID. Enter it and retry.
"This server requires static OAuth configuration."Same — enter the Client ID and click Configure again.
Fetch fails with 401Token expired or never authorized. Click Configure again to re-authorize.
Discovered tool list is emptyThe MCP server has no tools, or the URL is wrong. Verify the endpoint.
Agent never calls the tool in chatTool is enabled, but the LLM doesn't think it's relevant. Nudge it in the system prompt: "When the user asks about X, use the Y tool."

Save tools as templates for reuse​

If you add the same tool to multiple agents, it becomes available in the Pre-defined Tool catalog for future use. Select it from there on future agents to stamp it out quickly.

On this page