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: Streamable HTTP servers
• SSE Transport: Legacy Server-Sent Events servers

This page describes SuperQode consuming external MCP servers. To expose HarnessSpec workflows as an MCP server, use superqode mcp.

Configuration Location¶

MCP servers can be configured in two ways:

1. YAML Configuration (superqode.yaml):

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

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

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:

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:

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 ownership depends on the selected runtime:

Project-level mcp_servers definitions are available to SuperQode-managed client sessions, but they are not automatically injected into every vendor SDK. Use the runtime-specific documentation when the runtime owns its MCP lifecycle.

Runnable Harness Example¶

The repository includes a local FastMCP documentation server and a HarnessSpec that consumes it over stdio:

superqode harness run \
  --spec examples/harnesses/mcp-docs.yaml \
  --prompt "Find the documentation for MCP serving"

The example server is examples/mcp/local_docs_server.py. Its tool is exposed to the harness as mcp_docs_search_docs.

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:

1. Verify the project configuration is valid:

   superqode config validate
   

2. Start SuperQode or the harness MCP server and watch startup output for MCP connection errors:

   superqode
   superqode mcp --dir ./harnesses
   

3. Verify the configured MCP server command works outside SuperQode. For stdio servers, run the configured command directly and check that it starts.

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 config validate
superqode mcp --dir ./harnesses

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