MCP Configuration Guide

This document explains how to configure per-repository MCP (Model Context Protocol) servers for the Agent Manager.

Overview

The Agent Manager supports three levels of MCP configuration:

Repository-specific configuration - Unique MCP servers for each repository
Global default configuration - Shared MCP servers for all repositories
Hardcoded fallback - Built-in gogs-mcp server (automatic)

Configuration Priority

When processing an issue, the system looks for MCP configuration in this order:

~/.config/agent-manager/mcp/{owner}/{repo}.json - Repository-specific
~/.config/agent-manager/mcp/default.json - Global default
Hardcoded fallback (gogs-mcp only)

Configuration Directory

All MCP configuration files are stored in:

~/.config/agent-manager/mcp/
├── default.json                    # Global default config
├── fszontagh/
│   ├── agent-manager.json         # Config for fszontagh/agent-manager
│   └── my-project.json            # Config for fszontagh/my-project
└── otheruser/
    └── their-repo.json            # Config for otheruser/their-repo

Security Note: Configuration files should have restrictive permissions (600 or 400) since they may contain secrets like API keys or JWT tokens.

Configuration File Format

MCP configuration files use JSON format:

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Server Types

stdio - Standard input/output communication (most common)
http - HTTP-based communication
sse - Server-Sent Events communication

Environment Variable Substitution

Configuration files support ${VAR_NAME} syntax for environment variables. This allows you to keep secrets out of the config files:

{
  "mcpServers": {
    "api-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/api-mcp/dist/index.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "API_URL": "https://api.example.com"
      }
    }
  }
}

The ${MY_API_KEY} will be replaced with the value from process.env.MY_API_KEY at runtime.

Example Configurations

Example 1: Global Default (All Repositories)

File: ~/.config/agent-manager/mcp/default.json

{
  "mcpServers": {
    "gogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/gogs-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Example 2: Repository-Specific with Multiple Servers

File: ~/.config/agent-manager/mcp/fszontagh/my-app.json

{
  "mcpServers": {
    "gogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/gogs-mcp/dist/index.js"],
      "env": {}
    },
    "database": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/database-mcp/dist/index.js"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_USER": "${DB_USER}",
        "DB_PASSWORD": "${DB_PASSWORD}",
        "DB_NAME": "myapp"
      }
    },
    "slack": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/slack-mcp/dist/index.js"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_CHANNEL": "#deployments"
      }
    }
  }
}

Example 3: Different Configs for Different Projects

Project A (uses Gogs + PostgreSQL):

{
  "mcpServers": {
    "gogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/gogs-mcp/dist/index.js"],
      "env": {}
    },
    "postgres": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/postgres-mcp/dist/index.js"],
      "env": {
        "PGHOST": "${PGHOST}",
        "PGUSER": "${PGUSER}",
        "PGPASSWORD": "${PGPASSWORD}"
      }
    }
  }
}

Project B (uses Gogs + MongoDB + Redis):

{
  "mcpServers": {
    "gogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/gogs-mcp/dist/index.js"],
      "env": {}
    },
    "mongodb": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/mongodb-mcp/dist/index.js"],
      "env": {
        "MONGO_URI": "${MONGO_URI}"
      }
    },
    "redis": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/redis-mcp/dist/index.js"],
      "env": {
        "REDIS_URL": "${REDIS_URL}"
      }
    }
  }
}

Creating Configuration Files

Method 1: Manual Creation

Create the directory structure and file:

mkdir -p ~/.config/agent-manager/mcp/owner
nano ~/.config/agent-manager/mcp/owner/repo.json
chmod 600 ~/.config/agent-manager/mcp/owner/repo.json

Method 2: Using McpConfigManager API

import { McpConfigManager } from './client/dist/index.js';

// Create global default config
McpConfigManager.createDefaultConfig({
  mcpServers: {
    gogs: {
      type: 'stdio',
      command: 'node',
      args: ['/data/gogs-mcp/dist/index.js'],
      env: {}
    }
  }
});

// Create repository-specific config
McpConfigManager.createRepoConfig('owner', 'repo', {
  mcpServers: {
    gogs: {
      type: 'stdio',
      command: 'node',
      args: ['/data/gogs-mcp/dist/index.js'],
      env: {}
    },
    custom: {
      type: 'stdio',
      command: 'node',
      args: ['/path/to/custom-mcp/dist/index.js'],
      env: {
        'API_KEY': process.env.API_KEY
      }
    }
  }
});

Security Best Practices

File Permissions: Always set configuration files to 600 (owner read/write only)
```
chmod 600 ~/.config/agent-manager/mcp/owner/repo.json
```
Use Environment Variables: Never hardcode secrets in config files. Use ${VAR_NAME} syntax instead.
Restrict Directory Access: The MCP config directory should be readable only by the user running agent-manager:
```
chmod 700 ~/.config/agent-manager/mcp
```
Keep Secrets in .env: Store actual secret values in the agent-manager .env file or system environment variables.

Troubleshooting

Configuration Not Loading

Check the logs when an issue is processed. You should see one of:

Using repository-specific MCP config: ~/.config/agent-manager/mcp/owner/repo.json
Using global default MCP config: ~/.config/agent-manager/mcp/default.json
Using hardcoded default MCP config (gogs-mcp only)

Permission Warnings

If you see:

Warning: MCP config file has insecure permissions (644). Should be 600 or 400.

Fix with:

chmod 600 ~/.config/agent-manager/mcp/owner/repo.json

Environment Variables Not Substituted

Ensure the environment variable is set in the agent-manager process environment:

# In .env or systemd service file
export MY_API_KEY="secret-value"

Then restart the agent-manager service.

Examples

Example configuration files are provided in examples/:

mcp-config-default.json - Simple single-server config
mcp-config-multi-server.json - Multiple servers with env var substitution

Migration from Hardcoded Config

If you're currently using the default hardcoded gogs-mcp configuration, you can:

Keep using the default - No action needed, it will continue to work
Create a global default - Copy examples/mcp-config-default.json to ~/.config/agent-manager/mcp/default.json
Create repo-specific configs - For repositories that need custom MCP servers

The system is fully backward compatible with the existing behavior.

MCP-CONFIG.md 7.4 KB История Исходник