Skip to main content

Agent Configuration

Configure both STDIO and HTTP MCP servers for AI agents.

Overview​

MCP Gatekeeper allows you to configure MCP servers for multiple AI agents including:

  • Windsurf: AI-powered code editor
  • Claude Desktop: Anthropic's desktop application
  • Amazon Q: AWS's AI coding assistant
  • Gemini CLI: Google's command-line AI tool
  • GitHub Copilot: Microsoft's AI pair programmer

Adding Servers to Agents​

From the Web UI​

  1. Navigate to Agents page
  2. Select an agent from the list
  3. Click Add Server button
  4. Select a server from the unified list:
    • STDIO servers (blue badge) - Installed npm packages
    • HTTP servers (purple badge) - Remote HTTP servers
  5. For STDIO servers:
    • Enter a server name
    • Configure arguments (optional)
    • Add environment variables (optional)
  6. For HTTP servers:
    • Server name is automatically set
    • No additional configuration needed
  7. Click Add Server

Server Selection UI​

The server selection dialog shows both types in a single list:

[STDIO] @modelcontextprotocol/server-github  v1.0.0
[STDIO] @modelcontextprotocol/server-filesystem  v2.1.0
[HTTP]  github  ● Active  https://api.githubcopilot.com/...

Configuration Types​

STDIO Server Configuration​

For locally installed packages:

{
  "mcpServers": {
    "my-filesystem-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_DIRECTORIES": "/Users/username/projects",
        "MCPGK_AGENT_TYPE": "windsurf"
      }
    }
  }
}

Key Fields:

  • command: Executable command
  • args: Command-line arguments
  • env: Environment variables (including auto-injected MCPGK_AGENT_TYPE)

HTTP Server Configuration​

For remote HTTP servers:

Windsurf (uses serverUrl):

{
  "mcpServers": {
    "github": {
      "serverUrl": "http://127.0.0.1:8000/proxy/windsurf/github"
    }
  }
}

Gemini CLI (uses httpUrl):

{
  "mcpServers": {
    "github": {
      "httpUrl": "http://127.0.0.1:8000/proxy/gemini_cli/github"
    }
  }
}

Amazon Q, Claude, GitHub Copilot (use url):

{
  "mcpServers": {
    "github": {
      "url": "http://127.0.0.1:8000/proxy/amazon_q/github"
    }
  }
}

Key Points:

  • Proxy URL automatically configured with agent type in path
  • Headers stored securely in database
  • Agent type extracted from URL path for tracking
  • URL key varies by agent: serverUrl (Windsurf), httpUrl (Gemini CLI), url (others)
  • No environment variables needed for HTTP servers

Agent-Specific Configurations​

Windsurf​

Config Location: ~/.windsurf/settings.json

{
  "mcpServers": {
    "filesystem": { /* STDIO config */ },
    "github-api": { /* HTTP config */ }
  }
}

Amazon Q​

Config Location: ~/.aws/amazonq/agents/default.json

Same format as Windsurf.

Gemini CLI​

Config Location: ~/.gemini/settings.json

Important: Uses httpUrl instead of url for HTTP servers.

Claude Desktop​

Config Location (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

Same format as Windsurf.

Agent Type Tracking​

STDIO servers include MCPGK_AGENT_TYPE environment variable:

{
  "env": {
    "MCPGK_AGENT_TYPE": "windsurf"
  }
}

HTTP servers include agent type in the proxy URL path:

http://127.0.0.1:8000/proxy/{agent_type}/{server_name}

This enables:

  • Per-agent metrics tracking
  • Agent-specific monitoring
  • Usage analytics by agent type

Removing Servers​

From the Web UI​

  1. Navigate to Agents page
  2. Select the agent
  3. Find the server in the list
  4. Click Remove button
  5. Confirm removal

This updates the agent's configuration file automatically.

Configuration Files​

MCP Gatekeeper automatically detects and manages these configuration files:

AgentConfig Path
Windsurf~/.windsurf/settings.json
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
Amazon Q~/.aws/amazonq/agents/default.json
Gemini CLI~/.gemini/settings.json
GitHub Copilot~/.copilot/config.json

Best Practices​

  1. Use Descriptive Names: Name servers clearly (e.g., github-work, filesystem-projects)
  2. Test Before Adding: Verify servers work before adding to agents
  3. Environment Variables: Use env vars for configuration (API keys, paths)
  4. Keep Updated: Regularly update STDIO packages for security
  5. Monitor Usage: Check metrics to see which servers are used most
  6. Backup Configs: MCP Gatekeeper modifies agent configs - keep backups

Troubleshooting​

Server Not Appearing​

Problem: Added server doesn't appear in agent

Solutions:

  1. Restart the agent application
  2. Check agent config file was updated
  3. Verify server is installed/configured
  4. Check MCP Gatekeeper logs

Permission Errors​

Problem: Cannot write to config file

Solutions:

  1. Check file permissions on config directory
  2. Run MCP Gatekeeper with appropriate permissions
  3. Manually edit config file if needed

Wrong URL Format​

Problem: HTTP server not working in Gemini CLI

Solution: Gemini CLI uses httpUrl field instead of url

Next Steps​