Enterprise MCP Server Hub

A security-focused reference implementation of a multi-tenant Model Context Protocol (MCP) server hub. It exposes demo CRM, support, and billing connectors as MCP tools, resources, and prompts, with token-derived tenant identity, scope and role checks, approval-gated writes, and audit events.

Current scope: a runnable demo using synthetic connector fixtures and local SQLite persistence. It does not connect to a real CRM, helpdesk, or billing provider. The included static bearer-token verifier is for local development only.

Why this project

AI assistants need a consistent way to discover and invoke business capabilities. MCP standardizes the interface; this project demonstrates the governance layer that an enterprise hub needs around it: identity, scopes, organization boundaries, controlled writes, and auditability.

Related MCP server: external-ai-ecosystem-gateway

Features

• Official MCP Python SDK v2, exposing tools, a resource, and a prompt.

• Streamable HTTP endpoint at /mcp and local stdio transport.

• Token-derived organization identity; client-supplied tenant IDs are never trusted.

• Fine-grained scopes plus role checks for write/approval/audit tools.

• Demo CRM customer search, support ticket search, and billing invoice lookup.

• Ticket creation starts as a pending action; only an authorized approver can approve it and create a demo-local ticket.

• Tenant-scoped SQLite persistence for pending actions, tickets, and audit events.

• Atomic approval decisions; a request cannot be approved/rejected twice.

• Health endpoint, Docker Compose, tests, and GitHub Actions CI.

Architecture

MCP Host / Agent
      |
      | Streamable HTTP + Authorization: Bearer <token>
      v
Official MCP Python SDK v2
      |
      +--> TokenVerifier --> verified subject/client/scopes/org/role
      |
      +--> MCP tool registry
              |
              +--> Policy enforcement (scope + role)
              |
              +--> Connector adapters
              |      +--> Demo CRM
              |      +--> Demo Support
              |      +--> Demo Billing
              |
              +--> SQLite store
                     +--> Pending actions
                     +--> Demo tickets
                     +--> Audit events

Tool catalog

Also included:

• Resource: hub://catalog

• Prompt: investigate_customer(customer_name)

• Health endpoint: GET /health

Quick start

Python 3.11+ is required.

python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell
# .venv\\Scripts\\Activate.ps1

python -m pip install -e ".[dev]"
cp .env.example .env

Edit .env and keep the sample token configuration only for local development. Then start the HTTP MCP server:

uvicorn app.mcp_server:app --reload --host 127.0.0.1 --port 8000

MCP endpoint: http://127.0.0.1:8000/mcp

Health check: http://127.0.0.1:8000/health

The SDK's protected-resource metadata endpoint is also available under /.well-known/oauth-protected-resource/mcp.

Try it with the MCP Inspector

Run:

npx -y @modelcontextprotocol/inspector

Connect to the Streamable HTTP endpoint. Set the HTTP Authorization header to Bearer agent-demo-token to use read and ticket-request tools. Use approver-demo-token for approval and audit tools.

For a trusted local stdio integration, see docs/mcp-client-config.md.

Example end-to-end flow

1. Call support_request_ticket_creation using agent-demo-token.

2. The result contains approval_required: true and a pending action ID. No ticket has been created yet.

3. Call hub_list_pending_actions using approver-demo-token.

4. Call hub_decide_pending_action with the action ID and decision="approve".

5. The approved action is persisted and a demo-local ticket reference is returned.

6. Read hub_get_audit_events with the approver token.

Demo identities and scopes

The .env.example file includes four local identities:

All tokens also have hub:access, which the MCP HTTP authorization layer requires. The sample tokens are public demo credentials and must never be used outside a local sandbox.

Run tests

pytest
pytest --cov=app --cov-report=term-missing

The unit tests cover token claim mapping, scope and role enforcement, tenant isolation, approval state transitions, duplicate decisions, and audit separation. They test the policy and service layer without requiring an external MCP host or a live business system.

Run with Docker

cp .env.example .env
# Edit .env before exposing the service. The included tokens are demo-only.
docker compose up --build

The container stores SQLite data in a named volume. The sample compose setup binds the service to the host's published port; keep it behind a trusted network until real authentication and host allowlists are configured.

Project layout

app/
  connectors/demo_connectors.py  # synthetic CRM, support, and billing adapters
  security/identity.py           # token-to-identity mapping
  security/policy.py             # scope and role enforcement
  security/tokens.py             # development static token verifier
  storage/store.py               # SQLite approvals, tickets, and audit log
  services.py                     # service orchestration
  mcp_server.py                   # MCP tools, resources, prompt, HTTP app
  config.py

tests/
docs/
.github/workflows/ci.yml

Security boundaries and production checklist

• The official MCP SDK performs bearer-token verification for Streamable HTTP. This project's static verifier is a development-only example. Replace it with a real OAuth/OIDC JWT verifier or token-introspection integration.

• Validate issuer, signature, expiry, audience/resource binding, and scopes. Do not forward inbound bearer tokens to downstream providers.

• stdio does not carry HTTP auth headers. Its security boundary is the local process. The optional local identity bypass is off by default and must not be enabled for remote/untrusted processes.

• The HTTP transport has a localhost Host allowlist for this sample. Configure a precise allowed-host/origin policy and HTTPS before deployment.

• Demo connectors use synthetic data. Add provider-specific credentials, least- privilege API scopes, timeouts, retries, idempotency keys, and secret storage when implementing real integrations.

• The SQLite audit log is useful for a demo but is not tamper-evident. Export events to a protected append-only logging platform for production.

• Add rate limiting, request-size limits, monitoring, retention controls, backup, and security testing before public or multi-customer deployment.

References

• Official MCP Python SDK v2

• MCP Python SDK authorization guide

• MCP tool security considerations

License

MIT. See LICENSE.