Skip to content
InseeFrLabPublic

About

A lightweight Rust MCP gateway to centralize your company’s MCP servers

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

MCPortal logo

Démo with INSEE & IGN data

Warning

This project is currently in beta and under active development. Features may change, and some things may break. Feedback and contributions are welcome!

MCPortal aggregates several MCP servers declared in a YAML registry and exposes them to an MCP client (Claude, Claude Code…) as a single server.

MCP client ──HTTP──▶ MCPortal ──HTTP──▶ "insee" MCP server
                                 ├────▶ "melodi" MCP server
                                 └────▶ "geodata" MCP server

Rather than loading dozens of tools into the client's context, the gateway exposes three tools:

Tool Purpose
search_tools(query, limit?) full-text search (BM25) across the tools of every server; returns their name and inputSchema
call_tool(name, arguments) calls an upstream tool by its full name {server}_{tool}
send_feedback(server, author, feedback) records feedback in the logs (label FEEDBACK)

It also exposes a catalog as resources (catalog://servers, catalog://domains, catalog://servers/{name}, catalog://servers/{name}/tools, catalog://guide), readable without consuming context.

Features

  • MCP protocol 2026-07-28 (sessionless), compatible with older clients.
  • Stateless mode: several replicas without sticky sessions.
  • Arguments validated against the target tool's JSON Schema before any upstream call.
  • Transparent relaying of results, progress, cancellation and multi-turn exchanges (input_required).
  • Per-server concurrency limits, with a bounded wait time.
  • Upstream health probes; a failing upstream breaks neither the catalog nor the others.
  • JSON logs on standard output (Loki / Grafana) and Prometheus metrics.
  • /health (liveness), /ready (readiness) and graceful shutdown for Kubernetes.

Quick start

Requirements: Rust 1.88 or newer (2024 edition). No system dependency: TLS goes through rustls, without OpenSSL.

cargo run -- --config registry.yaml
Port Routes
8000 /mcp (MCP endpoint), /health, /ready (only /mcp goes through the ingress)
9090 /metrics (Prometheus)

To plug the gateway into Claude Code:

claude mcp add --transport http mcportal http://localhost:8000/mcp

Configuration

The whole configuration lives in the YAML registry (path given by --config or the MCPORTAL_CONFIG variable). Example:

gateway:
  name: SSP Gateway
  tool_search: {enabled: true, max_results: 5}
  catalog: {enabled: true, include_tool_inventory: true, include_guide: true, guide_path: guide-ssp.md}
  health: {enabled: true, path: /health, probe_interval_seconds: 60, failure_threshold: 2}
  metrics: {log_level: INFO, json_logs: true, prometheus: {enabled: true, port: 9090}}
  concurrency: {acquire_timeout_seconds: 5}
  # Local: loopback only + Host check. In Kubernetes: bind "0.0.0.0:8000" (see deploy/).
  http: {bind: "127.0.0.1:8000", path: /mcp, allowed_hosts: [localhost, 127.0.0.1, "::1"]}

servers:
  - name: mcpdiffusion            # unique name, also used as the tool prefix: [A-Za-z0-9-],
                                  # no '_'; search, call and send are reserved
    url: https://mcpdiffusion.lab.sspcloud.fr/mcp
    transport: http               # http (sse: deprecated, not supported)
    domain: diffusion
    description: Server exposing Melodi, Rmes and insee.fr
    tags: [dataset, publications] # list or single string
    enabled: true                 # false: visible in the catalog, not exposed
    timeout: 30.0                 # timeout per upstream call (s)
    max_concurrency: 4            # concurrent calls to this server
    cache_ttl: 300                # lifetime of the tool list cache (s)
  - name: geodata
    url: https://geollm.beta.ign.fr/geocontext/mcp
    transport: http
    domain: geographie
    description: Données géographiques de l'IGN
    tags: [carte]
    enabled: true
    timeout: 45.0
    max_concurrency: 8
    cache_ttl: 600
  - name: sirene
    url: https://mcpsirene.lab.sspcloud.fr/mcp
    transport: http
    domain: diffusion
    description: Données du répertoire d'entreprises sirene
    tags: [sirene]
    enabled: true
    timeout: 45.0
    max_concurrency: 8
    cache_ttl: 600

Every key has a default value; they are all documented in src/config.rs. An unknown key (typo) or an inconsistent value prevents startup, with an explicit message.

guide_path points to the deployment-specific guide: it is relative to the registry, checked at startup and re-read on every read of catalog://guide.

The RUST_LOG variable takes precedence over log_level (e.g. RUST_LOG=mcportal=debug).

Deployment

The image is published on GHCR by CI (.github/workflows/docker.yml):

docker pull ghcr.io/inseefrlab/mcportal:0.1.0   # or :latest
# local build:
docker build -t mcportal:0.1.0 .

To release: bump version in Cargo.toml, then push a matching tag (git tag v0.1.0 && git push origin v0.1.0). CI runs the tests, pushes the X.Y.Z, X.Y and latest tags and creates the GitHub Release.

A Kubernetes example (ConfigMap, Deployment, Service) is provided in deploy/kubernetes.yaml. Key points:

  • the registry and the guide are mounted from a ConfigMap into /config;
  • a config change is deployed through a rolling update (no hot reload);
  • terminationGracePeriodSeconds must exceed the largest upstream timeout;
  • port 9090 (/metrics) must not be exposed by the ingress.

Tests and measurements

cargo test                                   # unit and integration tests (no network)
cargo test --test guide_drift -- --ignored   # guide consistency with the registry and real upstreams
cargo bench --bench overhead                 # gateway overhead

Integration tests start real mock MCP servers on random ports: they need no external service.

Overhead measured locally: about 0.9 ms per relayed call, mostly due to the extra HTTP hop. In production, the mcportal_gateway_overhead_seconds metric gives the same measurement.

Documentation

Known limitations (V1)

  • No authentication and no per-user limit.
  • No configuration hot reload.
  • Upstream sse transport not supported (deprecated by the MCP spec).

The reasons for these choices are detailed in the Architecture Decision Records.

Contributing

Contributions are welcome: bug reports, feature ideas, documentation or code.

  1. Open an issue to describe the bug or discuss the change before starting.

  2. Create a branch from main (feat/…, fix/…, docs/…).

  3. Check that everything passes:

    cargo fmt --all --check
    cargo clippy --all-targets -- -D warnings
    cargo test
  4. Open a pull request against main.

The details (code conventions, commit messages, tests, checklist) are in CONTRIBUTING.md.

License

Distributed under the MIT license.

About

A lightweight Rust MCP gateway to centralize your company’s MCP servers

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages