Skip to content

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

FieldTypeRequiredDescription
type"stdio" | "url"YesServer transport type.
commandstringstdio onlyExecutable to run.
argsstring[]stdio onlyCommand arguments.
envobjectNoEnvironment variables passed to the process.
urlstringurl onlyHTTP endpoint URL.
headersobjecturl onlyHTTP 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:

agentsmesh.yaml
collaboration:
strategy: lock
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...