> ## Documentation Index > Fetch the complete documentation index at: https://docs.cowagent.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP Tools > Integrate external tool ecosystems via the Model Context Protocol CowAgent supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), allowing the Agent to directly invoke tens of thousands of community MCP tools. Configure `mcp.json` once and the tools are exposed to the LLM in exactly the same way as built-in tools — automatically selected and invoked. ## Web and Desktop Console The **MCP Tools** section of the Capabilities page in the **web console** and **desktop app** can add, edit, disable, and remove MCP servers without editing `mcp.json` by hand. * **Form or JSON**: fill in the form, or paste a standard `mcpServers` config in JSON mode (several servers at once), for example `{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}`. * **Test connection**: checks that each server is reachable and lists its tools. Saving runs the same check first; if it fails, fix the config or choose **Save anyway** (for servers that require authorization after saving). * **Storage**: written to the current Agent's `mcp.json`, in the same format as Claude Desktop / Cursor. * **Immediate effect**: changes apply from the next message, with no restart. stdio, SSE, and streamable HTTP transports are all supported. A disabled server stays in the file but is not booted. Add an MCP tool ## Configuration File CowAgent reads `~/cow/mcp.json`. If the file does not exist, no MCP tools are loaded — and no error is raised. For Docker deployments, the official `docker-compose.yml` already mounts the host's `./cow` directory to `/home/agent/cow` inside the container (i.e. the container user's `~/cow`). Just drop `mcp.json` into the host's `./cow/` directory and it will take effect. ### Standard Format Fully compatible with the MCP community standard, identical to Claude Desktop / Cursor: ```json theme={null} { "mcpServers": { "": { "command": "npx", "args": ["-y", "some-mcp-package"], "env": { "API_KEY": "your-key-here" } } } } ``` | Field | Required | Description | | - | - | - | | `command` | stdio | Executable to launch the server (e.g. `npx`, `python`, `uvx`) | | `args` | No | Arguments passed to `command` | | `env` | No | Environment variables for the subprocess, commonly used for API keys | | `url` | SSE / Streamable HTTP | Remote endpoint URL (alternative to `command`) | | `type` | Remote | Remote transport type: `sse` or `streamable-http` (defaults to `sse`) | | `headers` | No | Extra HTTP headers for remote requests (e.g. `Authorization`); Streamable HTTP only | | `scope` | No | OAuth scope, only for remote servers that require OAuth authorization (optional) | | `tool_name_prefix` | No | String prepended to this server's tool names in CowAgent, e.g. `myserver_`. Defaults to an empty string. Include any separator in the prefix. Use a unique prefix to avoid collisions with built-in tools or other servers. | | `disabled` | No | When `true`, this server is skipped — handy for temporary disabling | ### Full Example ```json theme={null} { "mcpServers": { "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" } } } } ``` * **fetch**: Generic web page fetcher that returns page text content. No API key required. * **github**: Access GitHub repos, issues, PRs, etc. Requires a Personal Access Token. ### Streamable HTTP with a Bearer Key For a remote server that authenticates with a static API key, set `type` explicitly — a remote URL without it falls back to `sse` — and pass the key in `headers`: ```json theme={null} { "mcpServers": { "my-remote-tools": { "type": "streamable-http", "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` * Header values are sent literally: `${API_KEY}` is **not** expanded from the environment. * The key is stored as plain text, so keep `mcp.json` out of version control. * An `Authorization` header selects static authentication and skips the OAuth flow below, even when the value is wrong. ## Let the Agent Configure It for You CowAgent ships with `read` / `write` / `edit` tools, so **you can simply send the MCP config to the Agent and ask it to write the file**: For example: ```markdown theme={null} Add this MCP to ~/cow/mcp.json: {"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}} ``` The Agent will: 1. Read the existing MCP config and merge the new server entry, preserving existing ones 2. Hot-reload the new MCP server, so the corresponding tools become available on the next message ## Web Authorization (OAuth) Some remote MCP servers require OAuth web authorization, and connecting to them directly returns `401`. CowAgent has a built-in standard OAuth flow, so **no manual token is needed** — just configure the server normally, for example: ```json theme={null} { "mcpServers": { "xmind": { "type": "streamable-http", "url": "https://app.xmind.com/api/mcp" } } } ``` When a server returns `401` on its first load, authorization starts automatically: running locally **opens the browser automatically**, while server deployments **print the authorization link to the log** for you to open in a browser. Once you approve, the server comes online immediately; tokens are refreshed automatically on expiry, so you never have to re-authorize. * **Requires the web service**: The authorization callback is received by the web console (default port `9899`), so the Web channel must be running. * **Credential storage**: Tokens are persisted in `~/.cow/mcp_oauth.json` and reused across restarts. * **Callback URL**: Defaults to `http://127.0.0.1:9899/mcp/oauth/callback`. If deployed on a server with the authorizing browser on another device, set `mcp_oauth_redirect_base` in `config.json` (e.g. `http://YOUR_IP:9899`). ## How It Works * **Async loading at startup**: All servers configured in `mcp.json` are loaded asynchronously in the background, never blocking the main loop — chat is usable immediately. * **Hot reload**: When you or the Agent modifies `mcp.json`, changed servers are automatically reloaded after the current message — no need to restart cow. * **Flat exposure**: Each method exposed by an MCP server appears as an individual tool. The LLM picks one directly without a second-stage decision. ## Supported Transports | Transport | Description | Config Field | | - | - | - | | **stdio** | Subprocess communication. The most common option, with the richest community ecosystem. | `command` + `args` | | **SSE** | HTTP Server-Sent Events. Legacy remote transport. | `url` (default) | | **Streamable HTTP** | New unified remote transport, gradually replacing SSE. | `type: "streamable-http"` + `url` | ## Troubleshooting | Symptom | What to Check | | - | - | | Agent has no MCP tools after startup | Verify that `~/cow/mcp.json` exists and contains valid JSON | | A specific server fails to load | Look for `[MCP] Server 'xxx' load failed` in startup logs — usually missing dependencies or API keys | | Changes to `mcp.json` aren't applied | Changes take effect on **the next message**. If the server config didn't actually change (e.g. only comments edited), no restart is triggered | | Docker deployment | Make sure host's `./cow` is mounted to `/home/agent/cow` in the container, then just drop `mcp.json` into host's `./cow/`. Or just ask the Agent to do it | ## Recommended MCP Marketplaces You can browse third-party MCP marketplaces and copy a JSON config to use directly, for example: * [mcp.so](https://mcp.so) — Global MCP service index * [ModelScope MCP Hub](https://modelscope.cn/mcp) — ModelScope's MCP hub, more reliable from mainland China Any MCP server that follows the standard protocol (stdio / SSE / Streamable HTTP) integrates with CowAgent out of the box. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.