MCP Tools

CowAgent supports the Model Context Protocol (MCP), 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.

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:

{
  "mcpServers": {
    "<server-name>": {
      "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)
`disabled`	No	When `true`, this server is skipped — handy for temporary disabling

Full Example

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_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.

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:

Add this MCP to ~/cow/mcp.json:

{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}

The Agent will:

Read the existing MCP config and merge the new server entry, preserving existing ones
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:

{
  "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 — Global MCP service index
ModelScope MCP Hub — 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.

Tools System

Built-in Tools

Optional Tools

MCP Tools

Configuration File

Standard Format

Full Example

Let the Agent Configure It for You

Web Authorization (OAuth)

How It Works

Supported Transports

Troubleshooting

Recommended MCP Marketplaces

​Configuration File

​Standard Format

​Full Example

​Let the Agent Configure It for You

​Web Authorization (OAuth)

​How It Works

​Supported Transports

​Troubleshooting

​Recommended MCP Marketplaces

Configuration File

Standard Format

Full Example

Let the Agent Configure It for You

Web Authorization (OAuth)

How It Works

Supported Transports

Troubleshooting

Recommended MCP Marketplaces