MCP Servers

OpenAgent connects to external tool backends using the MCP (Model Context Protocol) standard. MCP servers are configured as Server records (under the Servers menu) and attached to a Store via the MCP Server field.

Setting up an MCP server

1. Go to Servers → Add Server
2. Fill in:
   • Name: unique identifier (e.g., my-tools)
   • URL: the MCP server's StreamableHTTP endpoint (e.g., https://tools.example.com/mcp)
   • Token: optional Bearer token for authenticated servers
3. Save, then click Sync to fetch the server's tool list
4. Review the discovered tools — toggle IsAllowed off for any tools you want to block
5. Edit the Store and set MCP Server to this server record

Transport

OpenAgent uses StreamableHTTP transport to connect to MCP servers. The server must expose an HTTP endpoint implementing the MCP protocol. The token, if set, is sent as Authorization: Bearer <token>.

Tool allow-listing

After syncing, each tool discovered from the server appears with an IsAllowed flag. Disabling a tool removes it from the model's tool list for all chats using this server. Use this to expose only the tools relevant to a Store's purpose.

One MCP server per Store

A Store can have exactly one MCP Server at a time.

If you need tools from multiple MCP servers, either:

1. Combine tools into one server — aggregate tools from multiple upstreams into a single MCP endpoint
2. Proxy through a single MCP server — use a routing server that delegates calls to multiple backends

MCP vs. built-in tools

An MCP Server and the Store's Builtin Tools can coexist. The model sees all tools from both sources in one unified list. OpenAgent routes each tool call to the appropriate backend transparently.

Testing the connection

After attaching an MCP server, open a chat with the Store and ask the agent to perform a task the tools handle. Tool calls appear inline in the chat — you'll see the tool name, arguments, and result.

If tools aren't being called:

1. Verify the MCP server URL is reachable from OpenAgent's server (not just your local machine)
2. Check tool descriptions — vague descriptions cause the model to skip tools it should use
3. Add an explicit instruction in the system prompt: "When the user asks about X, always use the tool_name tool"

Related pages

• MCP Servers (full reference) — detailed setup guide with tool description best practices
• Built-in Tools — tools that ship with OpenAgent and need no external server