MCP Configuration - Devin Docs

Adding MCP Servers

Via Command Line

The quickest way to add an MCP server:

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

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 below.

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

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:

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
devin mcp enable <name>     # Enable a disabled server
devin mcp disable <name>    # Disable a server without removing it

Via Config File

Add servers directly to your config file’s mcpServers section:

Project config
User config
Local override

// .devin/config.json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@company/mcp-server"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Project-level servers are shared with your team via version control.

// ~/.config/devin/config.json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.js"],
      "env": {}
    }
  }
}

User-level servers apply to all your projects.

// .devin/config.local.json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@company/mcp-server"],
      "env": {
        "API_KEY": "my-personal-key"
      }
    }
  }
}

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
`disabled`	boolean	No	Set to `true` to skip this server (see Enabling and disabling servers)

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). Set `"sse"` explicitly if the server’s SSE endpoint is at a different path.
`headers`	object	No	Custom HTTP headers to include in requests
`oauthClientId`	string	No	Pre-registered OAuth client ID, for servers that don’t support dynamic client registration (DCR), e.g. GitHub. See the “Pre-registered OAuth clients” section below.
`oauthClientSecret`	string	No	OAuth client secret, for confidential clients. Pair with `oauthClientId`.
`oauthResource`	string	No	Override the RFC 8707 `resource` parameter sent in OAuth requests (default: the MCP server URL). Set to an empty string (`""`) to omit the parameter entirely, for providers that reject it. See OAuth resource override.
`disabled`	boolean	No	Set to `true` to skip this server (see Enabling and disabling servers)

Examples

GitHub (stdio)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Notion (HTTP with OAuth)

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "transport": "http"
    }
  }
}

After adding an OAuth-based server, run devin mcp login notion to authenticate. See Authentication below.

Linear (HTTP with OAuth)

{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.linear.app/mcp",
      "transport": "http"
    }
  }
}

Atlassian / Jira (HTTP with OAuth)

{
  "mcpServers": {
    "atlassian": {
      "url": "https://mcp.atlassian.com/v1/mcp",
      "transport": "http"
    }
  }
}

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.

Custom server (stdio)

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

devin mcp login <server-name>

For example:

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:

devin mcp login notion --scopes read,write

To remove stored OAuth credentials for a server:

devin mcp logout <server-name>

If the server supports OAuth, you will also be prompted to authenticate automatically when the server is first used.

Pre-registered OAuth clients

Most OAuth-based MCP servers support dynamic client registration (DCR), so Devin CLI registers itself automatically and you don’t need to provide any client credentials. Some providers (e.g. GitHub) don’t support DCR and instead require a pre-registered OAuth client. For those, supply the client ID — and a client secret if it’s a confidential client — via oauthClientId / oauthClientSecret:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "transport": "http",
      "oauthClientId": "Iv1.abc123def456",
      "oauthClientSecret": "${env:MY_MCP_CLIENT_SECRET}"
    }
  }
}

When oauthClientId is set, Devin CLI skips dynamic client registration and uses your pre-registered client during the OAuth flow. Run devin mcp login <name> (or trigger first use) to authenticate as usual. You can also set these from the command line when adding or logging into a server:

devin mcp add my-server <URL> --oauth-client-id <ID> --oauth-client-secret <SECRET>
devin mcp login my-server --oauth-client-id <ID> --oauth-client-secret <SECRET>

oauthClientId / oauthClientSecret are OAuth client credentials used during the authorization flow. They are not generic per-request credentials — if a server expects a static token, use headers (HTTP) or env (stdio) instead.

Don’t commit a client secret to a shared config. Reference it from an environment variable (${env:VAR}), read it from a file (${file:/path}), or put it in .devin/config.local.json (gitignored). See the “Managing Secrets” section below.

OAuth resource override

During OAuth authorization and token exchange, Devin CLI sends an RFC 8707 resource parameter so the authorization server can issue audience-restricted tokens. By default the value is the MCP server’s URL. Override it with oauthResource:

{
  "mcpServers": {
    "my-server": {
      "url": "https://my-server.example.com/mcp",
      "transport": "http",
      "oauthResource": ""
    }
  }
}

The field has three behaviors:

Unset (default): sends resource set to the MCP server URL.
Non-empty value: replaces the default with your value (e.g. a specific application ID URI).
Empty string (""): omits the resource parameter entirely from both the authorization URL and the token exchange.

You can also set it from the command line when adding or logging into a server:

devin mcp add my-server <URL> --oauth-resource ""
devin mcp login my-server --oauth-resource ""

Like other OAuth fields, oauthResource supports ${env:VAR} and ${file:/path} expansion.

Enabling and Disabling Servers

You can temporarily disable an MCP server without removing its configuration. A disabled server is skipped during tool discovery — its tools won’t appear and the server process won’t be started.

devin mcp disable <name>    # Disable a server
devin mcp enable <name>     # Re-enable it

This sets the "disabled": true flag on the server entry in the config file. Use -s/--scope to target a specific scope:

devin mcp disable -s project my-server
devin mcp enable -s user my-server

You can also set the flag directly in your config file:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@company/mcp-server"],
      "disabled": true
    }
  }
}

Disabling is useful when you want to keep a server’s configuration (including environment variables and OAuth credentials) but temporarily stop using it — for example, to reduce startup time or isolate an issue.

Managing Secrets

Never commit API keys or secrets to version control. Use .devin/config.local.json for sensitive values.

For team projects, the recommended pattern is:

Define the server in .devin/config.json with placeholder or no env vars
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:

{
  "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

Organization restrictions

If you’re on an enterprise team, your admin may restrict which MCP servers you can connect to. A server you’ve configured can be blocked if MCP is disabled for your team, or if it isn’t on your team’s allowlist or in an enforced MCP registry — in which case it won’t connect and its tools won’t be available. See Team Settings — MCP Registry for details.

Troubleshooting

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:

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:

devin mcp logout <server-name>
devin mcp login <server-name>

Server won't start

Verify the command works outside Devin CLI:

npx -y @modelcontextprotocol/server-github

Check that all required environment variables are set.

Tools not appearing

Ask the agent to list MCP servers and tools. The server may need a moment to initialize.

Permission denied

Check your permissions config. MCP tools default to prompting for approval. Add them to permissions.allow to auto-approve.

OAuth errors due to the resource parameter

Some authorization servers reject OAuth requests that include the RFC 8707 resource parameter. Set oauthResource to an empty string to omit the parameter:

{
  "mcpServers": {
    "my-server": {
      "url": "https://my-server.example.com/mcp",
      "oauthResource": ""
    }
  }
}

Then re-authenticate:

devin mcp logout my-server
devin mcp login my-server

See OAuth resource override for the full set of oauthResource behaviors.

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

​Adding MCP Servers

​Via Command Line

​Via Config File

​Server Configuration Options

​Local Command (stdio)

​Remote Server (Streamable HTTP)

​Examples

​Authentication

​Pre-registered OAuth clients

​OAuth resource override

​Enabling and Disabling Servers

​Managing Secrets

​MCP Permissions

​Organization restrictions

​Troubleshooting

Adding MCP Servers

Via Command Line

Via Config File

Server Configuration Options

Local Command (stdio)

Remote Server (Streamable HTTP)

Examples

Authentication

Pre-registered OAuth clients

OAuth resource override

Enabling and Disabling Servers

Managing Secrets

MCP Permissions

Organization restrictions

Troubleshooting