forge-armory

Forge Armory acts as an MCP protocol gateway that aggregates tools from multiple backend MCP servers. It provides a dynamic, database-backed configuration, an admin REST API, a CLI for managing backends, and metrics to monitor tool usage and performance. Once running, you can add backends (MCP servers) by pointing Armory at their /mcp endpoints, list backends, and query metrics to observe tool calls and latency. The included CLI commands let you manage your backends directly from the command line, enabling quick integration of new MCP servers into the gateway.

Prerequisites:

• Python environment and the uv tool (uvx) installed
• A PostgreSQL database (or another supported database) reachable by the Armory instance
• Basic networking access to run the gateway on your desired host/port

Installation steps:

1. Ensure Python and uvx are installed. If you don’t have uvx, install the package that provides the uv tooling.
2. Set up the database according to your environment (see environment variables below).
3. Install Forge Armory via your preferred package manager (the command shown uses uvx to install the package named forge-armory).

Example setup using uvx:

• Install (if not already installed) and start the server: uv sync

4. Configure environment variables (example values shown): ARMORY_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/forge_armory ARMORY_HOST=0.0.0.0 ARMORY_PORT=8080

5. Start the gateway (example): uvx forge-armory

6. Verify the service is running by hitting the health/metrics endpoints or using the CLI to list backends.

Notes:

• The exact package name for uvx may vary; replace forge-armory with the actual published package name if different in your environment.

Tips and common issues:

• Ensure the ARMORY_DATABASE_URL uses a supported database driver and includes the correct credentials.
• If the gateway cannot bind to the configured port, check firewall rules and whether another process is using that port.
• Use the Admin API and CLI to add and manage MCP backends dynamically; ensure backends expose an /mcp endpoint compatible with MCP protocol.
• Monitor metrics to detect high latency or error rates and adjust backends accordingly.
• When migrating environments, retain the same database schema version to avoid configuration drift.
• Validate environment variables before starting the gateway to avoid runtime errors.