MCP API

Manage Model Context Protocol (MCP) server configurations

Overview

The MCP API provides endpoints to retrieve and update Model Context Protocol (MCP) server configurations. MCP servers extend AI agents with external tools and capabilities.

Get MCP Configuration

GET /api/mcp/config

Retrieve the current Model Context Protocol (MCP) server configurations

Response

mcp_servers · object

Map of MCP server name to configuration object

Show MCP Server Config

enabled · boolean · default: "true"

Whether this MCP server is enabled

type · string · default: "stdio"

Transport type: stdio, sse, or http

command · string

Command to execute to start the MCP server (for stdio type)

args · array

Arguments to pass to the command (for stdio type)

env · object

Environment variables for the MCP server

url · string

URL of the MCP server (for sse or http type)

headers · object

HTTP headers to send (for sse or http type)

oauth · object

OAuth configuration for MCP HTTP/SSE servers

Show OAuth Config

enabled · boolean · default: "true"

Whether OAuth token injection is enabled

token_url · string

OAuth token endpoint URL

grant_type · string · default: "client_credentials"

OAuth grant type: client_credentials or refresh_token

client_id · string

OAuth client ID

client_secret · string

OAuth client secret

refresh_token · string

OAuth refresh token (for refresh_token grant type)

scope · string

OAuth scope

audience · string

OAuth audience

token_field · string · default: "access_token"

Token response field containing access token

token_type_field · string · default: "token_type"

Token response field containing token type

expires_in_field · string · default: "expires_in"

Token response field containing expires-in seconds

default_token_type · string · default: "Bearer"

Default token type when response omits token_type

refresh_skew_seconds · integer · default: "60"

Refresh this many seconds before expiry

extra_token_params · object

Additional form params sent to token endpoint

description · string

Human-readable description of what this MCP server provides

Example Request

curl http://localhost:8001/api/mcp/config

Example Response

{
  "mcp_servers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      },
      "url": null,
      "headers": {},
      "oauth": null,
      "description": "GitHub MCP server for repository operations"
    },
    "filesystem": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
      "env": {},
      "url": null,
      "headers": {},
      "oauth": null,
      "description": "Filesystem access MCP server"
    }
  }
}

---

Update MCP Configuration

PUT /api/mcp/config

Update Model Context Protocol (MCP) server configurations and save to file

Request Body

mcp_servers · object · required

Map of MCP server name to configuration (same structure as GET response)

Response

Returns the updated MCP configuration (same as GET response).

Example Request

curl -X PUT http://localhost:8001/api/mcp/config \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_servers": {
      "github": {
        "enabled": true,
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "$GITHUB_TOKEN"
        },
        "description": "GitHub MCP server for repository operations"
      }
    }
  }'

Example Response

{
  "mcp_servers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      },
      "url": null,
      "headers": {},
      "oauth": null,
      "description": "GitHub MCP server for repository operations"
    }
  }
}

Behavior

When you update the MCP configuration:

1. The new configuration is saved to extensions_config.json
2. The configuration cache is reloaded
3. The LangGraph Server (separate process) detects the config file change via mtime
4. MCP tools are automatically reinitialized with the new configuration

Error Responses

500 · Internal Server Error

Failed to update MCP configuration

{
  "detail": "Failed to update MCP configuration: [error details]"
}

---

MCP Server Types

stdio (Standard Input/Output)

The most common MCP server type. The server is spawned as a subprocess and communicates via stdin/stdout.

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "$GITHUB_TOKEN"
  }
}

SSE (Server-Sent Events)

HTTP-based server using Server-Sent Events for streaming responses.

{
  "type": "sse",
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer $API_TOKEN"
  }
}

HTTP

Standard HTTP-based MCP server.

{
  "type": "http",
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer $API_TOKEN"
  }
}

---

OAuth Configuration

For HTTP and SSE servers that require OAuth authentication, you can configure automatic token management:

{
  "type": "sse",
  "url": "https://api.example.com/mcp",
  "oauth": {
    "enabled": true,
    "token_url": "https://auth.example.com/oauth/token",
    "grant_type": "client_credentials",
    "client_id": "$CLIENT_ID",
    "client_secret": "$CLIENT_SECRET",
    "scope": "mcp.read mcp.write",
    "audience": "https://api.example.com",
    "refresh_skew_seconds": 60
  }
}

Grant Types

client_credentials

Used for server-to-server authentication:

{
  "grant_type": "client_credentials",
  "client_id": "$CLIENT_ID",
  "client_secret": "$CLIENT_SECRET"
}

refresh_token

Used when you have a refresh token:

{
  "grant_type": "refresh_token",
  "client_id": "$CLIENT_ID",
  "client_secret": "$CLIENT_SECRET",
  "refresh_token": "$REFRESH_TOKEN"
}

---

Environment Variables

You can reference environment variables in the configuration using the $VAR_NAME syntax:

{
  "env": {
    "GITHUB_TOKEN": "$GITHUB_TOKEN",
    "API_KEY": "$MY_API_KEY"
  },
  "headers": {
    "Authorization": "Bearer $API_TOKEN"
  }
}

Variables are resolved at runtime from the process environment.

---

Use Cases

List Configured Servers

const response = await fetch('http://localhost:8001/api/mcp/config');
const { mcp_servers } = await response.json();

// Get enabled servers
const enabledServers = Object.entries(mcp_servers)
  .filter(([_, config]) => config.enabled)
  .map(([name, _]) => name);

Add New Server

async function addMcpServer(serverName: string, config: any) {
  // Get current config
  const response = await fetch('http://localhost:8001/api/mcp/config');
  const currentConfig = await response.json();
  
  // Add new server
  currentConfig.mcp_servers[serverName] = config;
  
  // Update config
  const updateResponse = await fetch('http://localhost:8001/api/mcp/config', {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(currentConfig)
  });
  
  return updateResponse.json();
}

Disable Server

async function disableMcpServer(serverName: string) {
  const response = await fetch('http://localhost:8001/api/mcp/config');
  const config = await response.json();
  
  if (config.mcp_servers[serverName]) {
    config.mcp_servers[serverName].enabled = false;
    
    const updateResponse = await fetch('http://localhost:8001/api/mcp/config', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(config)
    });
    
    return updateResponse.json();
  }
}

---

Related

MCP Overview

Learn about Model Context Protocol

Gateway Overview

Learn about the Gateway API