MCP Servers

MCP is an open standard for exposing tools to language models. An MCP server defines a set of tools — each with a name, description, and parameter schema — that the model can call during a conversation. OpenAgent connects as an MCP client: it queries the server's tool list when a conversation starts and routes tool calls to the server during the conversation.

Any MCP-compatible server works with OpenAgent. No custom integration code is needed on the OpenAgent side.

How tool use works

When a conversation starts, OpenAgent queries the MCP server for its tool list. Each tool's name and description are included in the context sent to the model. During the conversation:

1. The model decides a tool is needed based on the user's request and the tool's description
2. The model emits a structured tool call: { "tool": "get_weather", "args": { "city": "Tokyo" } }
3. OpenAgent sends the call to the MCP server and waits for the result
4. The result is appended to the context: { "result": "Partly cloudy, 22°C" }
5. The model reasons again with the result in view and either calls another tool or produces a final response

Tool calls and results are shown inline in the chat UI and saved in the Message's toolCalls field.

Connecting an MCP server

Writing good tool descriptions

The model has no way to try a tool and see what happens. It relies entirely on the description to decide whether the tool is appropriate. Vague or generic descriptions lead to the wrong tool being called, the right tool not being called, or incorrect arguments being passed.

Good descriptions answer three questions:

1. What does this tool do?
2. When should the model use it (and when shouldn't it)?
3. What do the parameters mean?

Well-described tool:

{
  "name": "lookup_order",
  "description": "Look up the current status and details of a customer order by its order ID. Use this when the user asks about shipping, delivery, or order status. Do not use for billing or refund questions.",
  "parameters": {
    "order_id": {
      "type": "string",
      "description": "The order identifier. Format: ORD-XXXXXX (e.g. ORD-123456)"
    }
  }
}

Poorly described tool:

{
  "name": "get_order",
  "description": "Gets order info.",
  "parameters": {
    "id": { "type": "string" }
  }
}

The system prompt can also guide tool selection directly: "If the user asks about order status, always use lookup_order before responding."

Tool allow-listing

After syncing, the server record shows each discovered tool with an IsAllowed toggle. Disabling a tool removes it from the model's tool list for all chats using this server — the model never sees it and cannot call it.

Use this to restrict a server to only the tools relevant to a particular Store's purpose, or to disable dangerous tools that the server exposes but you don't want available in your deployment.

Combining MCP with built-in tools

An MCP Server and the Store's Builtin Tools can coexist. The model sees all tools in one unified list and decides which to call. OpenAgent routes each call to the appropriate backend — MCP server or built-in implementation — transparently.

A Store can only have one MCP Server at a time. If you need tools from multiple MCP servers, either:

• Combine the tools into a single MCP server
• Use an MCP server that proxies multiple upstreams

MCP ecosystem

The MCP documentation maintains a directory of open-source servers and SDKs. Commonly used servers include:

SDKs are available for TypeScript, Python, and other languages for building custom servers.