---
url: /api/schemas/mcp.md
description: >-
  Schema reference for .mcp.json MCP server configuration including all
  transport types.
---

# MCP Configuration

The `.mcp.json` file configures Model Context Protocol servers. It supports a wrapped format (`{ "mcpServers": { ... } }`) for project scope or a flat format (`{ "server-name": { ... } }`) for plugin scope.

## Fields

Server configuration varies by [transport type](/api/schemas#mcp-transport-types).

### stdio

Default transport when `command` is present.

| Field     | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `type`    | string   | no       | Optional, inferred from `command` |
| `command` | string   | yes      | Command to execute                |
| `args`    | string\[] | no       | Command arguments                 |
| `env`     | object   | no       | Environment variables             |
| `timeout` | number | no | Per-server timeout in milliseconds |
| `alwaysLoad` | boolean | no | Load tool definitions without deferring to tool search |

### http

| Field     | Type   | Required | Description           |
| --------- | ------ | -------- | --------------------- |
| `type`    | string | yes      | Must be `"http"`      |
| `url`     | string | yes      | HTTP endpoint URL     |
| `headers` | object | no       | HTTP headers          |
| `env`     | object | no       | Environment variables |
| `timeout` | number | no | Per-server timeout in milliseconds |
| `alwaysLoad` | boolean | no | Load tool definitions without deferring to tool search |
| `headersHelper` | string | no | Command printing dynamic request headers |
| `oauth` | object | no | OAuth options: `clientId`, `callbackPort`, `authServerMetadataUrl`, and space-separated `scopes` |

### sse (deprecated)

| Field     | Type   | Required | Description           |
| --------- | ------ | -------- | --------------------- |
| `type`    | string | yes      | Must be `"sse"`       |
| `url`     | string | yes      | SSE endpoint URL      |
| `headers` | object | no       | HTTP headers          |
| `env`     | object | no       | Environment variables |
| `timeout` | number | no | Per-server timeout in milliseconds |
| `alwaysLoad` | boolean | no | Load tool definitions without deferring to tool search |
| `headersHelper` | string | no | Command printing dynamic request headers |
| `oauth` | object | no | OAuth options: `clientId`, `callbackPort`, `authServerMetadataUrl`, and space-separated `scopes` |

### ws (WebSocket)

The config literal is `"ws"` — not `"websocket"`, which is not a valid value.

| Field     | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `type`    | string | yes      | Must be `"ws"`                                  |
| `url`     | string | yes      | WebSocket URL (`ws://` or `wss://`)             |
| `headers` | object | no       | Request headers (WebSocket auth is header-only) |
| `env`     | object | no       | Environment variables                           |
| `timeout` | number | no | Per-server timeout in milliseconds |
| `alwaysLoad` | boolean | no | Load tool definitions without deferring to tool search |
| `headersHelper` | string | no | Command printing dynamic request headers |
| `oauth` | object | no | OAuth options: `clientId`, `callbackPort`, `authServerMetadataUrl`, and space-separated `scopes` |

### streamable-http

A documented alias for `http`, accepted so configurations copied from MCP server
documentation work unmodified. Same fields as `http`.

## Example

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "analytics": {
      "type": "http",
      "url": "https://mcp.example.com/analytics"
    }
  }
}
```