MCP Configuration¶

Complete guide to configuring Model Context Protocol (MCP) servers in SuperQode.

Overview¶

MCP servers provide tools and resources that agents can use during SuperQode sessions and harness runs. SuperQode supports:

Stdio Transport: Local process-based servers
HTTP Transport: HTTP/HTTPS servers
SSE Transport: Server-Sent Events for streaming

Configuration Location¶

MCP servers can be configured in two ways:

YAML Configuration (superqode.yaml):

mcp_servers:
  filesystem:
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]

JSON Configuration (.superqode/mcp.json, ~/.superqode/mcp.json, or ~/.config/superqode/mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

Priority: YAML configuration takes precedence over JSON for SuperQode-managed MCP servers. ACP sessions read enabled MCP servers from the JSON MCP config locations and pass them to the ACP agent when a new session is created.

Web Fetch for ACP Agents¶

SuperQode's built-in fetch and web_fetch tools are available to the default SuperQode runtime. ACP agents such as OpenCode need fetch exposed through MCP. Add an enabled fetch server to one of the JSON MCP config locations:

{
  "mcpServers": {
    "fetch": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "enabled": true
    }
  }
}

Restart the ACP connection after editing this file. Existing ACP sessions keep the MCP server list they received at session creation.

Transport Types¶

Stdio Transport¶

Local process-based servers (most common):

mcp_servers:
  filesystem:
    transport: stdio
    enabled: true
    auto_connect: true
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "."
    env:
      NODE_ENV: production
    cwd: /path/to/workspace
    timeout: 30.0

Fields:

Field	Type	Description
`transport`	`"stdio"`	Transport type
`enabled`	boolean	Whether server is enabled
`auto_connect`	boolean	Auto-connect on startup
`command`	string	Executable command
`args`	array	Command arguments
`env`	object	Environment variables
`cwd`	string	Working directory
`timeout`	number	Connection timeout (seconds)

Semantic Code Search MCP¶

For AST-aware semantic repository search, install ccc and run cocoindex-code as a stdio MCP server:

uv tool install 'cocoindex-code'

mcp_servers:
  cocoindex-code:
    transport: stdio
    enabled: true
    auto_connect: true
    command: ccc
    args: ["mcp"]
    cwd: /path/to/workspace

Run ccc init --litellm-model ollama/nomic-embed-text and ccc index in the workspace first if you want local Ollama embeddings. The MCP server exposes a semantic search tool with query, limit, offset, languages, paths, and refresh_index.

For local laptops, note that ccc mcp starts a background index task and its search tool refreshes the index by default. For repeated searches after a manual ccc index, pass refresh_index=false to keep calls lightweight. See Semantic Code Search for the native semantic_search tool, MCP tradeoffs, and local-model setup.

HTTP Transport¶

HTTP/HTTPS servers for remote or containerized MCP servers:

mcp_servers:
  database:
    transport: http
    enabled: true
    auto_connect: true
    url: http://localhost:8080/mcp
    headers:
      Authorization: "Bearer ${MCP_DB_TOKEN}"
    timeout: 30.0
    sse_read_timeout: 300.0

Fields:

Field	Type	Description
`transport`	`"http"`	Transport type
`enabled`	boolean	Whether server is enabled
`auto_connect`	boolean	Auto-connect on startup
`url`	string	Server URL
`headers`	object	HTTP headers
`timeout`	number	Request timeout (seconds)
`sse_read_timeout`	number	SSE read timeout (seconds)

SSE Transport¶

Server-Sent Events for streaming responses:

mcp_servers:
  streaming:
    transport: sse
    enabled: true
    url: http://localhost:8080/mcp/events
    headers:
      Authorization: "Bearer ${TOKEN}"
    timeout: 5.0
    sse_read_timeout: 300.0

Fields:

Field	Type	Description
`transport`	`"sse"`	Transport type
`enabled`	boolean	Whether server is enabled
`auto_connect`	boolean	Auto-connect on startup
`url`	string	SSE endpoint URL
`headers`	object	HTTP headers
`timeout`	number	Connection timeout (seconds)
`sse_read_timeout`	number	SSE read timeout (seconds)

Common MCP Servers¶

Filesystem Server¶

Access local file system:

mcp_servers:
  filesystem:
    transport: stdio
    enabled: true
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "."

GitHub Server¶

Interact with GitHub repositories:

mcp_servers:
  github:
    transport: stdio
    enabled: true
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

PostgreSQL Server¶

Query PostgreSQL databases:

mcp_servers:
  postgres:
    transport: stdio
    enabled: true
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-postgres"
    env:
      POSTGRES_CONNECTION_STRING: "${POSTGRES_CONNECTION_STRING}"

Slack Server¶

Interact with Slack:

mcp_servers:
  slack:
    transport: stdio
    enabled: true
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-slack"
    env:
      SLACK_BOT_TOKEN: "${SLACK_BOT_TOKEN}"
      SLACK_TEAM_ID: "${SLACK_TEAM_ID}"

Brave Search Server¶

Search the web:

mcp_servers:
  brave-search:
    transport: stdio
    enabled: true
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-brave-search"
    env:
      BRAVE_API_KEY: "${BRAVE_API_KEY}"

MCP Server Assignment¶

MCP servers defined in mcp_servers are available to all sessions automatically.

Environment Variables¶

Use environment variables in MCP configuration:

mcp_servers:
  github:
    transport: stdio
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"  # Will read from $GITHUB_TOKEN

Variable Resolution:

${VAR_NAME}: Reads from environment
Default values: ${VAR_NAME:-default} (not supported, use explicit env vars)

Enabling/Disabling Servers¶

Enable All Servers¶

mcp_servers:
  filesystem:
    enabled: true
  github:
    enabled: true

Disable Specific Server¶

mcp_servers:
  filesystem:
    enabled: false  # Server defined but disabled
  github:
    enabled: true

Auto-Connect Control¶

mcp_servers:
  filesystem:
    enabled: true
    auto_connect: true   # Connect on startup
  github:
    enabled: true
    auto_connect: false  # Manual connection only

Troubleshooting¶

Server Not Starting¶

Problem: MCP server fails to start

Solution: Check command and environment:

mcp_servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
    env:
      DEBUG: "1"  # Enable debug logging

Connection Timeout¶

Problem: Server connection times out

Solution: Increase timeout:

mcp_servers:
  database:
    transport: http
    url: http://localhost:8080/mcp
    timeout: 60.0  # Increase from default 30.0

Tools Not Available¶

Problem: MCP tools not showing up

Solution:

Verify server is enabled:
```
superqode providers mcp list
```

Check server connection:

superqode providers mcp test filesystem

Verify MCP server connection:

Best Practices¶

1. Use Auto-Connect Selectively¶

Enable auto-connect only for frequently used servers:

mcp_servers:
  filesystem:
    auto_connect: true   # Always needed

  github:
    auto_connect: false  # Only when working with GitHub

2. Organize by Purpose¶

Group related servers:

# Development servers
mcp_servers:
  filesystem: {...}
  git: {...}

# External services
mcp_servers:
  github: {...}
  slack: {...}
  database: {...}

3. Use Environment Variables¶

Never hardcode secrets:

mcp_servers:
  github:
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"  # [CORRECT] Good
      # GITHUB_TOKEN: "ghp_..."        # [INCORRECT] Bad

4. Test Connections¶

Verify servers work before using:

superqode providers mcp test filesystem

JSON Configuration Format¶

MCP servers can also be configured in JSON format:

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "enabled": true,
      "autoConnect": true,
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ],
      "env": {
        "NODE_ENV": "production"
      },
      "timeout": 30.0
    }
  }
}

Note: YAML configuration in superqode.yaml takes precedence over JSON configuration.

Advanced Configuration¶

Multiple Instances¶

Run multiple instances of the same server:

mcp_servers:
  filesystem-workspace:
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

  filesystem-home:
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "~"]

Custom Working Directory¶

mcp_servers:
  filesystem:
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
    cwd: /path/to/project  # Override working directory

Custom Headers for HTTP¶

mcp_servers:
  api:
    transport: http
    url: https://api.example.com/mcp
    headers:
      Authorization: "Bearer ${API_TOKEN}"
      X-API-Version: "v2"
      User-Agent: "SuperQode/1.0"

Next Steps¶

YAML Reference - Complete configuration reference