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.
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). |
Servers from packs and extends
Installed packs and extends sources can ship their own mcp.json. Their servers are added to the list in your own mcp.json, and your server wins when both use the same name. Generate then writes the whole list to each tool, so a server that is only in a tool’s own config can be dropped.
This happens only when your own mcp.json has a mcpServers key. Without it (no file, or the key commented out, as init --global scaffolds it), AgentsMesh does not manage your tools’ MCP servers: generate skips the servers from packs and extends and prints a warning, and the servers in your tools stay as they are. To start managing them, run agentsmesh import --from <tool> (add --global for ~/.agentsmesh) to copy in the servers your tools already have, then run agentsmesh generate.
Tool-specific behavior
See the MCP Servers row in the supported tools matrix for per-target support levels (native, partial, or unsupported).
Locking MCP servers from accidental changes
For sensitive MCP configs (production endpoints, auth-required servers), use collaboration.lock_features:
collaboration: strategy: lock lock_features: - mcpWith mcp locked, agentsmesh generate will not overwrite MCP config without --force.
Referencing MCP servers from agents
---name: github-assistantdescription: Agent with GitHub MCP accessmcpServers: - githubtools: - Read - Grep---
You have access to the GitHub MCP server for repository operations...