MCP Servers

MCP (Model Context Protocol) server definitions live in .agentsmesh/mcp.json. Define your servers once and AgentsMesh generates the correct format for each tool that supports MCP.

File format

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "internal-api": {
      "type": "url",
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer $API_TOKEN"
      }
    }
  }
}

Server types

stdio servers

Run a local process and communicate via stdin/stdout:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "$DATABASE_URL"
      }
    }
  }
}

URL servers

Connect to an HTTP endpoint:

{
  "mcpServers": {
    "internal-tools": {
      "type": "url",
      "url": "https://mcp.internal.company.com/tools",
      "headers": {
        "Authorization": "Bearer $INTERNAL_API_KEY",
        "X-Team": "platform"
      }
    }
  }
}

Environment variables

Use $VAR_NAME syntax for environment variables. They are resolved at runtime by each tool — AgentsMesh does not expand them during generation.

Caution

Never hardcode secrets in mcp.json. Always use $ENV_VAR references. The file is committed to git.

Server configuration fields

Field	Type	Required	Description
type	"stdio" | "url"	Yes	Server transport type.
command	string	stdio only	Executable to run.
args	string[]	stdio only	Command arguments.
env	object	No	Environment variables passed to the process.
url	string	url only	HTTP endpoint URL.
headers	object	url only	HTTP headers (e.g., auth tokens).

Tool-specific behavior

Tool	Support	Notes
Claude Code	Native	.claude/settings.json mcpServers field.
Cursor	Native	.cursor/mcp.json.
Copilot	—	Not supported.
Gemini CLI	Native	.gemini/settings.json mcpServers.
Cline	Native	.cline/mcp.json.
Codex CLI	Native	AGENTS.md embedded MCP config.
Windsurf	Partial	Windsurf has limited MCP server support.
Continue	Native	.continue/config.json mcpServers.
Junie	Native	.junie/mcp.json.

Locking MCP servers from accidental changes

For sensitive MCP configs (production endpoints, auth-required servers), use collaboration.lock_features:

agentsmesh.yaml

collaboration:
  strategy: merge
  lock_features:
    - mcp

With mcp locked, agentsmesh generate will not overwrite MCP config without --force.

Referencing MCP servers from agents

---
name: github-assistant
description: Agent with GitHub MCP access
mcpServers:
  - github
tools:
  - Read
  - Grep
---

You have access to the GitHub MCP server for repository operations...