> ## Documentation Index
> Fetch the complete documentation index at: https://cli.devin.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Configuration

> How to add, configure, and manage MCP servers

## Adding MCP Servers

### Via Command Line

The quickest way to add an MCP server:

```bash theme={null}
# stdio server — just pass the command after --
devin mcp add <name> -- <command> [args...]

# HTTP server — pass the URL as a positional argument
devin mcp add <name> <URL>

# HTTP server — or use the --url flag
devin mcp add <name> --url <URL>
```

The transport type is inferred automatically: a URL implies HTTP (Streamable HTTP), and trailing args (or `--command`) imply stdio.

> [!NOTE]
>
> Remote MCP servers use Streamable HTTP by default. If the server responds with an HTTP 4xx error, the CLI falls back to SSE on the same URL. Set `"transport": "sse"` explicitly if needed — see [Legacy SSE fallback](#legacy-sse-fallback) below.

By default, servers are saved to **local** scope (`.devin/config.local.json`, gitignored). Use `-s`/`--scope` to change:

```bash theme={null}
devin mcp add -s project <name> <URL>   # shared via .devin/config.json
devin mcp add -s user <name> <URL>      # global (~/.config/devin/config.json; %APPDATA%\devin\config.json on Windows)
```

You can also manage servers from the command line:

```bash theme={null}
devin mcp list              # List all configured servers
devin mcp get <name>        # Show details for a specific server
devin mcp remove <name>     # Remove a configured server
devin mcp login <name>      # Authenticate with a server via OAuth
devin mcp logout <name>     # Remove stored OAuth credentials
```

### Via Config File

Add servers directly to your config file's `mcpServers` section:

> [tab] Project config
>
> ```json theme={null}
> // .devin/config.json
> {
>   "mcpServers": {
>     "server-name": {
>       "command": "npx",
>       "args": ["-y", "@company/mcp-server"],
>       "env": {
>         "API_KEY": "your-key"
>       }
>     }
>   }
> }
> ```
>
> > [!NOTE]
> >
> > Project-level servers are shared with your team via version control.

> [tab] User config
>
> ```json theme={null}
> // ~/.config/devin/config.json
> {
>   "mcpServers": {
>     "my-server": {
>       "command": "node",
>       "args": ["/path/to/my-server.js"],
>       "env": {}
>     }
>   }
> }
> ```
>
> > [!NOTE]
> >
> > User-level servers apply to all your projects.

> [tab] Local override
>
> ```json theme={null}
> // .devin/config.local.json
> {
>   "mcpServers": {
>     "server-name": {
>       "command": "npx",
>       "args": ["-y", "@company/mcp-server"],
>       "env": {
>         "API_KEY": "my-personal-key"
>       }
>     }
>   }
> }
> ```
>
> > [!NOTE]
> >
> > Local configs are gitignored — use these for personal API keys.

***

## Server Configuration Options

MCP servers can be configured in two ways: as a **local command** (stdio transport) or as a **remote server** (HTTP transport).

### Local Command (stdio)

| Field | Type | Required | Description |
| - | - | - | - |
| `command` | string | Yes | The executable to run |
| `args` | string\[] | No | Command-line arguments |
| `env` | object | No | Environment variables to set |

### Remote Server (Streamable HTTP)

| Field | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | The URL of the MCP server endpoint |
| `transport` | string | No | `"http"` (Streamable HTTP, default for URL-based servers) or `"sse"` (legacy SSE). When set to `"http"` or omitted, the CLI tries Streamable HTTP first and falls back to SSE on 4xx errors ([per spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility)). Set `"sse"` explicitly if the server's SSE endpoint is at a different path. |
| `headers` | object | No | Custom HTTP headers to include in requests |

### Examples

> [accordion] GitHub (stdio)
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "github": {
>       "command": "npx",
>       "args": ["-y", "@modelcontextprotocol/server-github"],
>       "env": {
>         "GITHUB_TOKEN": "ghp_..."
>       }
>     }
>   }
> }
> ```

> [accordion] Notion (HTTP with OAuth)
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "notion": {
>       "url": "https://mcp.notion.com/mcp",
>       "transport": "http"
>     }
>   }
> }
> ```
>
> > [!NOTE]
> >
> > After adding an OAuth-based server, run `devin mcp login notion` to authenticate. See [Authentication](#authentication) below.

> [accordion] Linear (HTTP with OAuth)
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "linear": {
>       "url": "https://mcp.linear.app/mcp",
>       "transport": "http"
>     }
>   }
> }
> ```

> [accordion] Atlassian / Jira (HTTP with OAuth)
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "atlassian": {
>       "url": "https://mcp.atlassian.com/v1/mcp",
>       "transport": "http"
>     }
>   }
> }
> ```
>
> > [!NOTE]
> >
> > After adding, run `devin mcp login atlassian` to authenticate. Each MCP client (Windsurf, Claude Code, Devin CLI) maintains its own OAuth session, so you must log in separately even if you've already authenticated in another tool.

> [accordion] Custom server (stdio)
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "my-tools": {
>       "command": "python",
>       "args": ["./scripts/mcp-server.py"],
>       "env": {
>         "DB_URL": "postgres://localhost/mydb"
>       }
>     }
>   }
> }
> ```

***

## Authentication

Some remote MCP servers require OAuth authentication. After adding an OAuth-based server to your config, authenticate using the `login` command:

```bash theme={null}
devin mcp login <server-name>
```

For example:

```bash theme={null}
devin mcp login notion    # Authenticate with Notion
devin mcp login linear    # Authenticate with Linear
```

This opens a browser window where you can authorize access. The OAuth tokens are stored locally and refreshed automatically.

You can optionally request specific OAuth scopes:

```bash theme={null}
devin mcp login notion --scopes read,write
```

To remove stored OAuth credentials for a server:

```bash theme={null}
devin mcp logout <server-name>
```

> [!NOTE]
>
> If the server supports OAuth, you will also be prompted to authenticate automatically when the server is first used.

***

## Managing Secrets

> [!WARNING]
>
> Never commit API keys or secrets to version control. Use `.devin/config.local.json` for sensitive values.

For team projects, the recommended pattern is:

1. Define the server in `.devin/config.json` with placeholder or no env vars
2. Each team member adds their personal keys in `.devin/config.local.json`

The local config file is automatically excluded from git.

***

## MCP Permissions

You can pre-approve, deny, or force-ask for specific MCP tools in your permissions config:

```json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",
      "mcp__github__create_issue"
    ],
    "deny": [
      "mcp__github__delete_repo"
    ],
    "ask": [
      "mcp__linear__*"
    ]
  }
}
```

**Permission matcher patterns:**

| Pattern | Matches |
| - | - |
| `mcp__server__tool` | A specific tool on a specific server |
| `mcp__server__*` | All tools on a specific server |
| `mcp__*` | All MCP tools on all servers |

***

## Troubleshooting

> [accordion] Auth required / OAuth errors with remote servers
>
> If you see errors like `Auth required` or `AuthRequired` when connecting to a remote MCP server, the server requires OAuth authentication.
>
> Run:
>
> ```bash theme={null}
> devin mcp login <server-name>
> ```
>
> Each MCP client authenticates independently. Even if you've already authenticated in Windsurf or Claude Code, you need to run `devin mcp login` separately for Devin CLI.
>
> To verify your auth status, try removing and re-adding credentials:
>
> ```bash theme={null}
> devin mcp logout <server-name>
> devin mcp login <server-name>
> ```

> [accordion] Server won't start
>
> Verify the command works outside Devin CLI:
>
> ```bash theme={null}
> npx -y @modelcontextprotocol/server-github
> ```
>
> Check that all required environment variables are set.

> [accordion] Tools not appearing
>
> Ask the agent to list MCP servers and tools. The server may need a moment to initialize.

> [accordion] Permission denied
>
> Check your permissions config. MCP tools default to prompting for approval. Add them to `permissions.allow` to auto-approve.

> [accordion] Legacy SSE fallback
>
> When connecting to an HTTP server, Devin CLI tries **Streamable HTTP** first. If the server responds with an HTTP 4xx error (e.g. 404 or 405), it automatically falls back to **legacy SSE** on the **same configured URL**. This follows the [MCP spec's backwards-compatibility guidance](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility).
>
> The fallback only triggers on 4xx responses — connection errors, timeouts, and 5xx responses are reported directly without attempting SSE.
>
> If your server's SSE endpoint is at a different path (e.g. `/sse` instead of `/mcp`), set `"transport": "sse"` with the SSE URL to connect directly without the Streamable HTTP attempt.
>
> If both transports fail, the error message includes details from both attempts to help with troubleshooting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.