OpenAgent
ConnectorsTools

MCP (Model Context Protocol)

How OpenAgent connects to MCP servers, how tool calls work, and how to write effective tool descriptions.

MCP (Model Context Protocol)

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 acts as an MCP client: it queries the server's tool list at conversation start and routes tool calls to the server during the conversation.

Any MCP-compatible server works with OpenAgent. No custom integration code is required.

For setup steps (adding a Server record, syncing tools, attaching to a Store), see Servers.

How tool calls work

When a conversation starts, OpenAgent fetches the MCP server's tool list. Each tool's name and description are injected into 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 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 with the result 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.

OpenAgent queries the MCP server's tool list at conversation start. Changes to the server's exposed tools are reflected immediately in new conversations. Use Sync on the Server record after modifying the server's tool list to update the cached allowlist.

Writing good tool descriptions

The model relies entirely on descriptions to decide whether and how to use a tool. Vague descriptions produce wrong tool selection, missed calls, and incorrect arguments.

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: "If the user asks about order status, always use lookup_order before responding."

MCP ecosystem

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

ServerWhat it does
@modelcontextprotocol/server-filesystemRead and write local files
@modelcontextprotocol/server-githubSearch repos, read files, create issues
@modelcontextprotocol/server-postgresQuery PostgreSQL with natural language
@modelcontextprotocol/server-slackSend messages, read channel history
@modelcontextprotocol/server-fetchFetch and extract content from URLs

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

Transport

OpenAgent uses StreamableHTTP as the MCP transport. The Server record's URL must point to a StreamableHTTP endpoint. The optional Token field is sent as a Bearer token in the Authorization header.

  • Servers — add Server records, sync tools, manage the allowlist
  • Built-in Tools — tools bundled with OpenAgent requiring no external server

On this page

MCP (Model Context Protocol)How tool calls workWriting good tool descriptionsMCP ecosystemTransportRelated