Agent MCP Gateway

# Configuration Quick Start Guide This guide will help you set up and validate your Agent MCP Gateway configuration. ## Step 1: Set Up Environment Variables Copy the example environment file and customize it: ```bash cp .env.example .env ``` Edit `.env` and set your actual values: ```bash # Required for brave-search server BRAVE_API_KEY=your_actual_brave_api_key # Required for postgres server POSTGRES_URL=postgresql://user:password@localhost:5432/database ``` **Load environment variables:** ```bash # Option 1: Source the file source .env # Option 2: Use with commands export $(cat .env | xargs) ``` **Note for GUI Applications (Claude Desktop, etc.):** If using `${VAR_NAME}` syntax in `.mcp.json`, macOS GUI applications don't access shell environment variables. Add API keys to the gateway's `env` object in your MCP client configuration instead. See README.md "Environment Variables" section for details. (Not needed if you hardcode values in `.mcp.json` without `${VAR_NAME}` syntax.) ## Step 2: Review Configuration Files ### MCP Servers Configuration Edit `.mcp.json` (or `config/.mcp.json`) to define your MCP servers: **Note:** `.mcp.json` is the standard MCP configuration file format used by Claude Code and other coding agents. If you already have a `.mcp.json` file in your development environment, the gateway can use it directly. ```json { "mcpServers": { "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" } } } } ``` **Transport Types:** - **stdio:** Use `command`, `args`, and optional `env` - **HTTP:** Use `url` and optional `headers` ### Gateway Rules Configuration Edit `.mcp-gateway-rules.json` (or `config/.mcp-gateway-rules.json`) to define agent policies: **Note:** `.mcp-gateway-rules.json` follows the same naming pattern as `.mcp.json` and is designed for version control and team sharing. All team members can use the same agent access policies by checking this file into your repository. ```json { "agents": { "researcher": { "allow": { "servers": ["brave-search"], "tools": { "brave-search": ["*"] } } }, "default": { "deny": { "servers": ["*"] } } }, "defaults": { "deny_on_missing_agent": false } } ``` **Agent Identity Options:** The gateway supports flexible agent identity with a fallback chain: 1. **Explicit agent_id in tool calls** (recommended for multi-agent setups) 2. **Environment variable** (`GATEWAY_DEFAULT_AGENT`) for single-agent mode 3. **"default" agent** in rules file (fallback when `deny_on_missing_agent` is false) **The `deny_on_missing_agent` Setting:** - **`true` (Strict Mode):** Rejects tool calls without `agent_id`, bypassing fallback chain - use in production multi-agent environments - **`false` (Fallback Mode):** Uses the fallback chain above - use in single-agent/development environments **Single-Agent Mode Example:** ```bash export GATEWAY_DEFAULT_AGENT=researcher uv run python main.py # Now all tools work without passing agent_id explicitly ``` **Secure Default Agent:** The "default" agent above denies all servers, following the principle of least privilege. This ensures requests without explicit agent identity are rejected safely unless you've configured a specific default via environment variable. **Wildcard Patterns:** - `"*"` - All tools - `"get_*"` - All tools starting with `get_` - `"*_query"` - All tools ending with `_query` ## Step 3: Validate Configuration Run the validation script: ```bash python validate_config.py ``` **Expected output for valid configuration:** ``` Agent MCP Gateway - Configuration Validator MCP Servers Config: /path/to/.mcp.json Gateway Rules: /path/to/.mcp-gateway-rules.json Loading MCP server configuration... ✓ Loaded 3 server(s): - brave-search (stdio) - postgres (stdio) - filesystem (stdio) Loading gateway rules... ✓ Loaded 3 agent policy(ies): - researcher - backend - admin Cross-validating rules against servers... ✓ All rules reference valid servers ✓ Configuration is valid and ready to use! ``` ## Step 4: Use in Your Code ```python import os from src.config import ( load_mcp_config, load_gateway_rules, validate_rules_against_servers, get_config_path ) # Ensure environment variables are set # (or load from .env using python-dotenv) # Get configuration paths # Default checks .mcp.json in current dir, then ./config/.mcp.json mcp_config_path = get_config_path( "GATEWAY_MCP_CONFIG", ".mcp.json" ) rules_path = get_config_path( "GATEWAY_RULES", ".mcp-gateway-rules.json" ) # Load configurations mcp_config = load_mcp_config(mcp_config_path) rules = load_gateway_rules(rules_path) # Validate cross-references warnings = validate_rules_against_servers(rules, mcp_config) if warnings: for warning in warnings: print(f"Warning: {warning}") # Use configurations servers = mcp_config["mcpServers"] agents = rules["agents"] ``` ## Common Issues ### Issue: Missing Environment Variable **Error:** ``` ValueError: Environment variable "BRAVE_API_KEY" referenced in configuration but not set. Please set this variable before starting the gateway. ``` **Solution:** ```bash export BRAVE_API_KEY=your_api_key ``` ### Issue: Server Not Found **Error:** ``` Warning: Agent "researcher" allow.servers references undefined server "unknown-server" ``` **Solution:** Add the server to `.mcp.json` or remove the reference from gateway rules. ### Issue: Invalid JSON **Error:** ``` JSONDecodeError: Invalid JSON in MCP server configuration: Expecting ',' delimiter ``` **Solution:** Check your JSON syntax. Common issues: - Missing commas between objects - Trailing commas (not allowed in strict JSON) - Unquoted keys or values - Unescaped quotes in strings ### Issue: Invalid Wildcard Pattern **Error:** ``` ValueError: Agent "test" allow.tools["server"][0]: wildcard in pattern "get_*_all" must be at start, end, or alone ``` **Solution:** Use valid wildcard patterns: - ✓ `"*"` - ✓ `"get_*"` - ✓ `"*_query"` - ✗ `"get_*_all"` (wildcard in middle) ## Testing Your Configuration Run the test suite to ensure everything works: ```bash python test_config.py ``` All tests should pass: ``` ✓ Valid MCP config test passed ✓ Environment variable substitution test passed ✓ Missing environment variable error test passed ... ✓ All tests passed! ``` ## Next Steps 1. **Review** `src/CONFIG_README.md` for detailed documentation 2. **Customize** agent policies in `.mcp-gateway-rules.json` 3. **Add** more MCP servers to `.mcp.json` 4. **Integrate** the configuration module into the gateway server **Tip:** Both `.mcp.json` and `.mcp-gateway-rules.json` are designed for version control. Check them into your repository to ensure your entire team uses consistent MCP server configurations and agent access policies! ## Environment Variable Reference | Variable | Default | Description | |----------|---------|-------------| | `GATEWAY_MCP_CONFIG` | `.mcp.json` (fallback: `./config/.mcp.json`) | Path to MCP servers config | | `GATEWAY_RULES` | `.mcp-gateway-rules.json` (fallback: `./config/.mcp-gateway-rules.json`) | Path to gateway rules config | | `GATEWAY_DEFAULT_AGENT` | *(none)* | Default agent when `agent_id` not provided (optional) | | `GATEWAY_DEBUG` | `false` | Enable debug mode to expose `get_gateway_status` tool | | `BRAVE_API_KEY` | *(required)* | API key for Brave Search | | `POSTGRES_URL` | *(required)* | PostgreSQL connection URL | ## Additional Resources - **MCP Server Documentation:** https://modelcontextprotocol.io - **FastMCP Documentation:** https://github.com/jlowin/fastmcp - **Project PRD:** `docs/specs/PRD.md` - **FastMCP Implementation Guide:** `docs/fastmcp-implementation-guide.md`