---
draft: false
title: MCP Servers
description: MCP server definitions in AgentsMesh use a JSON format compatible with the Model Context Protocol. Define stdio and HTTP servers once, generate for all supported tools.
---

import { Aside } from '@astrojs/starlight/components';

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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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.

<Aside type="caution">
  Never hardcode secrets in `mcp.json`. Always use `$ENV_VAR` references. The file is committed to git.
</Aside>

## 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

See the **MCP Servers** row in the [supported tools matrix](../../reference/supported-tools/) 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`:

```yaml
# 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

```markdown
---
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...
```
