MCP Server Configuration¶

The Model Context Protocol (MCP) allows AI assistants to connect to external tools and data sources.

Overview¶

MCP servers provide:

Tools: Functions the AI can call
Resources: Data sources the AI can access
Prompts: Pre-defined prompt templates

Configuration Format¶

All supported assistants use similar JSON configuration:

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Assistant-Specific Locations¶

Assistant	Config File
Claude Code	`~/.claude.json`
Gemini CLI	`~/.gemini/settings.json`
OpenAI Codex	`~/.codex/config.json`
AWS Kiro	`~/.kiro/mcp.json`

Canonical Format¶

AI Assist Kit provides a canonical MCP configuration format:

type MCPServerConfig struct {
    Command string            `json:"command"`
    Args    []string          `json:"args,omitempty"`
    Env     map[string]string `json:"env,omitempty"`
}

type MCPConfig struct {
    Servers map[string]MCPServerConfig `json:"mcpServers"`
}

Common MCP Servers¶

Filesystem Server¶

Access local files:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

GitHub Server¶

Access GitHub repositories:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

PostgreSQL Server¶

Access PostgreSQL databases:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/db"
      }
    }
  }
}

Slack Server¶

Access Slack workspaces:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-slack"],
      "env": {
        "SLACK_TOKEN": "xoxb-your-token"
      }
    }
  }
}

Converting Between Assistants¶

import (
    "github.com/agentplexus/assistantkit/mcp/core"
    "github.com/agentplexus/assistantkit/mcp/claude"
    "github.com/agentplexus/assistantkit/mcp/kiro"
)

// Define canonical config
config := core.MCPConfig{
    Servers: map[string]core.MCPServerConfig{
        "filesystem": {
            Command: "npx",
            Args:    []string{"-y", "@anthropic-ai/mcp-server-filesystem"},
        },
    },
}

// Convert to Claude format
claudeConfig := claude.FromCanonical(config)

// Convert to Kiro format
kiroConfig := kiro.FromCanonical(config)

Per-Agent MCP Configuration¶

Some assistants support per-agent MCP configuration:

AWS Kiro¶

{
  "name": "database-agent",
  "description": "Agent with database access",
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"]
    }
  },
  "includeMcpJson": true
}

The includeMcpJson: true option merges the global ~/.kiro/mcp.json configuration.

Security Considerations¶

Sensitive Data

Never commit MCP configurations with secrets to version control. Use environment variables or secret management tools.

Using Environment Variables¶

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Restricting Access¶

Limit filesystem access to specific directories:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-server-filesystem",
        "/home/user/projects",
        "--read-only"
      ]
    }
  }
}

Troubleshooting¶

Server Not Starting¶

Check the command exists: which npx
Verify package is installed: npx -y @anthropic-ai/mcp-server-filesystem --help
Check logs for errors

Permission Denied¶

Verify the directory/resource is accessible
Check environment variables are set correctly
Ensure tokens have required scopes

Connection Timeout¶

Check network connectivity
Verify firewall rules
Increase timeout settings if available