MCP Ops Gateway

An MCP server that:

1. Exposes RAG search + ServiceNow + Observability as tools to any MCP client.
2. Acts as an MCP client itself, proxying calls to remote ServiceNow and Observability MCP servers.

Built on standalone FastMCP 3.x (PrefectHQ), not the mcp v2 beta bundled class — as of mid-2026, the standalone package is the stable, production choice for composing/proxying multiple MCP servers.

1. Install

python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env   # fill in real values

2. Run locally (stdio, for Claude Desktop)

python server.py

Add to Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "ops-gateway": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-gateway/server.py"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "...",
        "SERVICENOW_MCP_URL": "...",
        "SERVICENOW_CLIENT_ID": "...",
        "SERVICENOW_CLIENT_SECRET": "...",
        "SERVICENOW_TOKEN_URL": "...",
        "OBSERVABILITY_MCP_URL": "...",
        "OBSERVABILITY_API_KEY": "..."
      }
    }
  }
}

3. Run in production (Streamable HTTP)

export MCP_GATEWAY_TRANSPORT=streamable-http
export MCP_GATEWAY_AUTH_TOKEN=$(openssl rand -hex 32)
python server.py

Or via Docker:

docker build -t mcp-ops-gateway .
docker run -p 8080:8080 --env-file .env mcp-ops-gateway

Clients then connect to http://your-host:8080/mcp with Authorization: Bearer <MCP_GATEWAY_AUTH_TOKEN>.

4. Debug with MCP Inspector

npx @modelcontextprotocol/inspector http://localhost:8080/mcp

Architecture notes / production decisions

• Curated proxying, not blind forwarding. tools/servicenow_tools.py and tools/observability_tools.py don't just relay every remote tool. Each tool is explicitly defined with its own Pydantic-validated schema, docstring (which becomes the tool description the LLM sees), and error handling. This is deliberate: exposing a remote server's full raw tool surface to an agent is both a security risk (e.g. accidental delete_record exposure) and a UX problem (vague, remote-server-authored descriptions make for worse agent tool selection).

• Auth is mandatory over HTTP transport. server.py refuses to start with streamable-http transport unless MCP_GATEWAY_AUTH_TOKEN is set. For real production, replace StaticTokenVerifier with an OAuth 2.1 / JWT verifier tied to your IdP (Okta/Azure AD) — FastMCP supports pluggable AuthProviders for this.

• Remote calls get retry + backoff (clients/base_client.py, via tenacity), because remote MCP servers over a network WILL occasionally time out or drop connections. Only transport-level errors are retried — a 4xx/validation error from the remote tool is NOT retried.

• Short-lived connections per call. Each call_tool opens and closes its own connection to the remote server. This is simplest and safest for low/medium QPS. If you're calling a remote server dozens of times/sec, switch to a connection pool / persistent Client held in an contextlib.AsyncExitStack at server startup instead — see FastMCP docs on Client lifecycle for the pattern.

• ServiceNow OAuth token caching (clients/servicenow_client.py). ServiceNow's REST/MCP layer expects OAuth2 client-credentials tokens, not static API keys. The token is cached in-process and refreshed 60s before expiry rather than fetched on every call.

• RAG embedding model is baked into the Docker image at build time (see Dockerfile) so pod cold-starts don't depend on reaching HuggingFace at runtime — important if your network egress is locked down (as is typical in BFSI environments).

• mask_error_details: consider setting this True on FastMCP(...) in production so internal exception text (which might leak infra details) isn't sent verbatim to the LLM/client. Currently tool-level code catches and summarizes errors instead, which is the safer default.

Extending

To add a new remote MCP server (e.g. a CMDB or a paging system):

1. Add a client in clients/<name>_client.py following the ServiceNow or Observability pattern (whichever auth style matches).
2. Add curated tool wrappers in tools/<name>_tools.py.
3. Register in server.py: <name>_tools.register(mcp).

Known remote-server assumption

This code assumes your ServiceNow and Observability remote MCP servers expose generic tools like get_record/create_record/update_record and query_timeseries/search_logs/list_active_monitors respectively. Adjust the tool_name strings and argument shapes in tools/servicenow_tools.py and tools/observability_tools.py to match whatever remote MCP servers you're actually pointing at — run list_tools() via RemoteMCPClient against your real remote server first to see its actual tool names/schemas.