MCP Servers

The Model Context Protocol (MCP) lets you extend OpenCode with external tools and services. Connect databases, APIs, and custom tools to your Forkline runners.

What is MCP?

MCP is a standard protocol for connecting AI assistants to external systems. With MCP servers, OpenCode can:

  • Query databases directly
  • Access internal APIs
  • Search documentation
  • Integrate with external services

Info: MCP servers run in the runner environment alongside your code. They have access to the same network and resources.

Built-in vs MCP Tools

Built-in ToolsMCP Servers
Included by defaultAdded via configuration
File operations, bashExternal services, APIs
Always availableEnabled per project

Context7

Search through documentation for any library:

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Usage:

Look up how to configure caching in Next.js 15. Use context7.

Sentry

Access Sentry issues and projects:

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

Usage:

Show me the latest unresolved issues in the frontend project. Use sentry.

Grep.app

Search code snippets across GitHub:

{
  "mcp": {
    "gh-grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Usage:

Find examples of Prisma transactions in open source projects. Use gh-grep.

Database Servers

Connect directly to databases:

{
  "mcp": {
    "postgres": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": {
        "POSTGRES_URL": "{env:DATABASE_URL}"
      }
    }
  }
}

Configuring MCP in Forkline

Repository Configuration

Add MCP servers to your repository’s OpenCode configuration:

Create .opencode/config.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  }
}

Using Secrets

Reference repository secrets in MCP configuration:

{
  "mcp": {
    "internal-api": {
      "type": "remote",
      "url": "https://api.internal.company.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:INTERNAL_API_KEY}"
      }
    }
  }
}

Add INTERNAL_API_KEY to your repository secrets.

MCP Server Types

Remote Servers

Hosted MCP servers accessed via HTTP:

{
  "mcp": {
    "server-name": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Local Servers

Run MCP servers locally in the runner:

{
  "mcp": {
    "server-name": {
      "type": "local",
      "command": ["npx", "-y", "mcp-server-package"],
      "environment": {
        "API_KEY": "{env:API_KEY}"
      }
    }
  }
}

OAuth Authentication

For servers requiring OAuth:

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {
        "scope": "project:read project:write"
      }
    }
  }
}

OpenCode handles the OAuth flow automatically when you first use the server.

Enabling and Disabling

Control which servers are active:

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    },
    "internal-tools": {
      "type": "local",
      "command": ["./mcp-server"],
      "enabled": false
    }
  }
}

Using MCP Tools

Once configured, MCP tools are available alongside built-in tools.

Explicit Request

Search the Next.js docs for App Router patterns. Use context7.

Implicit via Rules

Add to your AGENTS.md:

## External Resources

When you need documentation for libraries, use the context7 MCP server.

Checking Available Tools

Ask OpenCode:

What MCP tools are available?

Permissions

Control MCP tool access per agent:

{
  "agent": {
    "build": {
      "permission": {
        "context7_*": "allow",
        "sentry_*": "ask"
      }
    },
    "plan": {
      "permission": {
        "context7_*": "allow",
        "sentry_*": "allow"
      }
    }
  }
}

Performance Considerations

Context Usage

Each MCP server adds tools to OpenCode’s context:

  • More tools = more tokens
  • Can impact performance
  • Enable only what you need

Recommendation

{
  "mcp": {
    "essential-server": {
      "enabled": true
    },
    "rarely-used-server": {
      "enabled": false
    }
  }
}

Enable frequently-used servers. Disable others until needed.

Creating Custom MCP Servers

Build your own MCP servers for internal tools:

Example: Internal API Server

// mcp-server.ts
import { Server } from '@modelcontextprotocol/sdk';

const server = new Server({
  name: 'internal-api',
  version: '1.0.0'
});

server.tool('get_user', {
  description: 'Get user by ID from internal API',
  parameters: {
    userId: { type: 'string' }
  },
  handler: async ({ userId }) => {
    const response = await fetch(
      `https://api.internal.company.com/users/${userId}`
    );
    return response.json();
  }
});

server.start();

Configure in your repository:

{
  "mcp": {
    "internal-api": {
      "type": "local",
      "command": ["node", "./mcp-server.ts"],
      "environment": {
        "API_TOKEN": "{env:INTERNAL_API_TOKEN}"
      }
    }
  }
}

Troubleshooting

Server Not Appearing

  1. Check enabled: true in config
  2. Verify the URL or command is correct
  3. Check runner logs for errors
  4. Ensure environment variables are set

Authentication Failures

  1. Re-run OAuth flow
  2. Check API keys in secrets
  3. Verify token hasn’t expired

Timeout Errors

Increase timeout for slow servers:

{
  "mcp": {
    "slow-server": {
      "type": "remote",
      "url": "https://slow.example.com/mcp",
      "timeout": 10000
    }
  }
}

Next Steps