Skip to main content

MCP Servers

Model Context Protocol (MCP) servers provide tool integration for Claude Code and Claude Desktop.

Overview​

MCP enables Claude to interact with external services through standardized tool interfaces. RavenmaskOS uses MCP for:

  • GitLab integration - Repository access, issues, merge requests
  • Linear integration - Project management, issue tracking
  • GitHub integration - External repository access
  • Bifrost tools - Custom AI platform tools via MCP gateway

Configuration​

MCP servers are configured in ~/.claude/mcp-servers.json:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@smithery/cli@latest", "run", "linear", "--key", "<api-key>"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<token>"
      }
    }
  }
}

This file is symlinked to Claude Desktop config:

ln -s ~/.claude/mcp-servers.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

GitLab MCP Server (Self-Hosted)​

Container: mcp-server-gitlab Port: 9400 (internal) Image: Custom build

Provides Claude Code access to self-hosted GitLab repositories.

Configuration​

Located at ~/ravenhelm/services/mcp-server-gitlab/.env:

# GitLab Connection
GITLAB_BASE_URL=https://gitlab.ravenhelm.dev
GITLAB_API_URL=http://gitlab  # Internal Docker network
GITLAB_PROJECT_PATH=ravenhelm/hlidskjalf
GITLAB_VERIFY_SSL=true

# Authentication
GITLAB_MCP_TOKEN=<gitlab-pat>

# Optional: Zitadel OAuth validation
ZITADEL_BASE_URL=https://zitadel.ravenhelm.dev

# Server Port
MCP_SERVICE_PORT=9400

Capabilities​

  • Repository browsing
  • File read/write
  • Merge request management
  • Issue tracking
  • Pipeline status

Linear MCP Server​

Project management integration via Smithery CLI.

Setup​

# Get API key from 1Password
op item get "Linear API Key" --vault ravenmask --fields credential --reveal

# Add to mcp-servers.json
{
  "linear": {
    "command": "npx",
    "args": ["-y", "@smithery/cli@latest", "run", "linear", "--key", "<api-key>"]
  }
}

Capabilities​

  • List/create/update issues
  • Manage projects and cycles
  • Team management
  • Workflow states

GitHub MCP Server​

External GitHub repository access.

Setup​

# Uses official MCP server
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "<token>"
    }
  }
}

Capabilities​

  • Repository access
  • Issues and PRs
  • File operations
  • Actions workflows

Bifrost MCP Gateway​

Custom MCP tools exposed through Bifrost. See [[../AI-ML-Platform/Bifrost-MCP-Gateway]] for details.

Architecture​

Claude Code → MCP Protocol → Bifrost API → Tool Executors
                                              ↓
                                    ┌─────────┴─────────┐
                                    │                   │
                              NornsDelegateExecutor  N8nWorkflowExecutor
                                    │                   │
                                Norns Agent        n8n Workflows

Config Sync​

MCP configuration syncs between machines via Claude Config:

  • GitHub repo: github.com/nwalker85/claudeconfig
  • Sync agent: ~/.claude/sync-agent/agent.py
  • n8n webhook: https://n8n.ravenhelm.dev/webhook/claude-config-sync

Changes to ~/.claude/mcp-servers.json automatically propagate to all machines.

Adding New MCP Servers​

  1. Find or create server:

  2. Add to config:

    # Edit config
    vi ~/.claude/mcp-servers.json

    # Restart Claude Code/Desktop

  3. Test:

    # In Claude Code
    > Use the <tool_name> tool to test

Troubleshooting​

Server Not Loading​

# Check JSON syntax
cat ~/.claude/mcp-servers.json | jq .

# Verify npx can run the server
npx -y @modelcontextprotocol/server-github --help

# Check Claude Code logs
tail -f ~/.claude/debug/*.log

Authentication Errors​

  • Verify API keys are valid
  • Check token permissions
  • Ensure network access to APIs

Connection Issues​

# Test GitLab connectivity
curl -H "PRIVATE-TOKEN: <token>" https://gitlab.ravenhelm.dev/api/v4/projects

# Test Linear API
curl -H "Authorization: <key>" https://api.linear.app/graphql

See Also​

  • [[../AI-ML-Platform/Bifrost-MCP-Gateway]] - Custom MCP tools
  • [[GitLab]] - GitLab server setup
  • [[Container-Management]] - Docker operations