Add MCP & external tools

Advanced · ~15 min · Prerequisites: an MCP server

What you'll do

Register an MCP server with your org, expose its tools to a specific agent, and verify the tools work in the test panel before publishing.

What MCP adds

Model Context Protocol (MCP) servers let you connect an agent to any external capability that isn't covered by built-in tools or Composio actions — a proprietary API, an internal data service, a specialized computation engine, or a third-party tool your team already runs. The agent calls MCP tools the same way it calls built-in ones; the difference is that the tool logic lives on your server, not inside Opisense. See Tools & integrations for the full architecture.

Register an MCP server

Before an agent can use an MCP server's tools, the server must be registered at the org level:

1. Go to Settings and find the MCP servers section (or the path your admin has configured).
2. Click + Add server and enter the server URL, a display name, and any authentication headers the server requires (API keys, bearer tokens).
3. Save. Opisense contacts the server to fetch its tool manifest. If the server is reachable and the manifest is valid, the tools appear as available.

The server registration is shared across the org. Any agent can then be given access to its tools.

Expose its tools to the agent

With the MCP server registered, add its tools to your agent:

1. Open /admin/agents/<slug>/edit and click Tools.
2. Click + Add tool and filter by the MCP server name or browse the External category.
3. Select the specific tools you want this agent to call. Each tool you add appears in the agent's active tool list.

Keep the selection narrow. Give the agent only the tools its role requires — not the entire server manifest. This keeps the agent's behavior predictable and limits the blast radius if something goes wrong.

Test and limit scope

Open the test panel and send a prompt that should invoke one of the MCP tools. Inspect the trace to confirm:

• The right tool was called.
• The parameters the agent sent match what your instructions described.
• The server's response came back correctly and the agent used it sensibly.

If a tool call fails, check the server's health first (the error in the trace will usually point to a network or auth issue). If the tool fires but the agent uses the result incorrectly, refine your instructions to be more explicit about when and how to use that tool.

Once the tools behave correctly, proceed to Scope agent permissions to set guardrails before publishing.

Try this next