@ereslibre I asked Rover to write the documentation for the MCP server configuration in rover.json using this workflow. The result was fine. Most of the content was well-written and examples were on point.

In the future, we might want to improve it by referencing existing files to mimic the existing styling.

Wdyt?

Configuring MCP Servers in rover.json

This guide explains how to configure MCP (Model Context Protocol) servers in rover.json to extend AI agent capabilities with external tools and services.

What you'll learn: How to add, configure, and troubleshoot MCP servers for AI agents

Prerequisites

Before configuring MCP servers, ensure you have:

• Rover CLI installed and initialized (rover init completed)
• At least one AI agent installed (Claude, Codex, Gemini, or Qwen)
• Docker available for isolated task environments
• MCP server executable or URL accessible

What are MCP Servers?

MCP (Model Context Protocol) allows AI agents to connect to external tools and services, extending capabilities beyond built-in features. By configuring MCP servers in rover.json, you can give agents access to:

• External APIs (databases, cloud services, third-party tools)
• Custom tooling specific to your project
• Additional data sources and integrations

When to use MCP servers:

• Access external APIs (GitHub, Slack, databases)
• Provide custom tools for your codebase
• Interact with internal services or infrastructure
• Extend agents with community-built MCP servers

Quick Start

The rover.json file is located in your project root and created by rover init.

Add your first MCP server:

{
  "version": "1.2",
  "languages": ["typescript"],
  "packageManagers": ["npm"],
  "taskManagers": [],
  "attribution": true,
  "mcps": [
    {
      "name": "filesystem",
      "commandOrUrl": "npx -y @modelcontextprotocol/server-filesystem /path/to/directory",
      "transport": "stdio"
    }
  ]
}

Test your configuration:

rover task "List files using the filesystem MCP"

The agent automatically receives MCP tools during task execution.

Configuration Structure

The mcps field is an array of MCP server configurations:

{
  "version": "1.2",
  "mcps": [
    {
      "name": "string",              // Required: unique identifier
      "commandOrUrl": "string",      // Required: command or URL
      "transport": "stdio|http|sse", // Required: communication method
      "envs": ["KEY=VALUE"],         // Optional: environment variables
      "headers": ["KEY: VALUE"]      // Optional: HTTP headers
    }
  ]
}

Required Fields

Optional Fields

Environment Variables Example:

"envs": [
  "API_KEY=sk_123456",
  "DEBUG=true",
  "MAX_RETRIES=3"
]

Headers Example:

"headers": [
  "Authorization: Bearer token123",
  "X-API-Version: 2.0",
  "Accept: application/json"
]

Transport Types

Choosing a transport:

• Use stdio: Local package managers (npm, pip), most community MCP servers
• Use http: Remote REST APIs, HTTP authentication needed
• Use sse: Real-time streaming, server-sent events required

Configuration Examples

Local MCP with Environment Variables

{
  "version": "1.2",
  "mcps": [
    {
      "name": "github",
      "commandOrUrl": "npx -y @modelcontextprotocol/server-github",
      "transport": "stdio",
      "envs": ["GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token"]
    }
  ]
}

Remote API with Authentication

{
  "version": "1.2",
  "mcps": [
    {
      "name": "custom-api",
      "commandOrUrl": "https://api.example.com/mcp/v1",
      "transport": "http",
      "headers": [
        "Authorization: Bearer sk_prod_abc123",
        "X-API-Version: 2.0"
      ]
    }
  ]
}

Multiple MCP Servers

{
  "version": "1.2",
  "mcps": [
    {
      "name": "filesystem",
      "commandOrUrl": "npx -y @modelcontextprotocol/server-filesystem /workspace",
      "transport": "stdio"
    },
    {
      "name": "database",
      "commandOrUrl": "python -m database_mcp",
      "transport": "stdio",
      "envs": ["DB_HOST=localhost", "DB_PORT=5432"]
    },
    {
      "name": "external-api",
      "commandOrUrl": "https://tools.example.com/mcp",
      "transport": "http",
      "headers": ["Authorization: Bearer token_xyz"]
    }
  ]
}

Agent-Specific Support

Different AI agents have varying MCP support levels:

Key limitations:

• Codex: No headers in stdio mode, no sse support
• Gemini/Qwen: May require additional security flags

Recommendation: Test MCPs with your specific agent. Use Claude for complex MCP configurations.

How MCPs are Applied

MCPs are automatically configured during task execution:

1. Task Creation: rover task "description" reads mcps from rover.json
2. Workspace Setup: Isolated Docker environment created
3. MCP Installation: Each MCP automatically installed in task workspace
4. Agent Configuration: Agent receives MCP configuration commands
5. Tool Availability: Agent can use MCP tools during execution
6. Cleanup: Environment cleaned up after task completion

Key points:

• No manual installation needed per task
• Changes to rover.json take effect on next task
• Each task gets fresh MCP setup
• Configuration applied in isolated environment

Troubleshooting

Invalid Format Errors

Environment variables must use KEY=VALUE (equals, no spaces):

// ✅ Correct
"envs": ["API_KEY=value123"]

// ❌ Wrong
"envs": ["API_KEY: value123"]  // Colon instead of equals
"envs": ["API_KEY = value"]    // Spaces around equals

Headers must use KEY: VALUE (colon-space):

// ✅ Correct
"headers": ["Authorization: Bearer token"]

// ❌ Wrong
"headers": ["Authorization=Bearer token"]  // Equals instead of colon
"headers": ["Authorization:Bearer token"]  // Missing space

JSON syntax issues:

• Use double quotes ", not single quotes '
• Include commas between array items
• Validate with a JSON linter

Transport Mismatch

URLs require http or sse transport:

// ❌ Wrong
{"commandOrUrl": "https://api.example.com", "transport": "stdio"}

// ✅ Correct
{"commandOrUrl": "https://api.example.com", "transport": "http"}

Local commands require stdio transport:

// ❌ Wrong
{"commandOrUrl": "npx @package/mcp", "transport": "http"}

// ✅ Correct
{"commandOrUrl": "npx @package/mcp", "transport": "stdio"}

MCP Server Not Working

Diagnostic steps:

1. Verify MCP is accessible:

   # For stdio: test command locally
   npx @modelcontextprotocol/server-github --help
   
   # For http/sse: test endpoint
   curl https://api.example.com/mcp

2. Check environment variables:

   • Verify KEY=VALUE format
   • Ensure required variables are provided
   • Check for special characters needing escaping

3. Review agent limitations:

   • Remove headers if using Codex with stdio
   • Verify transport is supported by your agent
   • Check Support Matrix table above

4. Check Rover task logs:

   • Look for MCP-related errors during setup
   • Verify installation commands succeeded
   • Check for authentication failures

5. Test MCP in isolation:

   # Manual installation to test
   rover-agent config mcp

Common issues:

• Missing dependencies: MCP requires additional packages
• Authentication failures: Verify API keys/tokens are correct
• Permission errors: Ensure necessary file/network permissions
• Version conflicts: Check MCP compatibility with your agent

Related Documentation

• AI Agents Documentation - Overview of AI agents in Rover
• MCP Specification - Official protocol documentation
• Popular MCP Servers - Community implementations

Next Steps

1. Browse available MCP servers for your use case
2. Add MCP configuration to rover.json
3. Test with a simple task: rover task "test MCP functionality"
4. Review agent-specific documentation for advanced features

Wdyt?

I like the wording and the technical details are correct. 👍