convez.ai
MCP ServerIntegração & APIsAvançado
MikkoParkkola

MCP Gateway

MikkoParkkola/mcp-gateway

Multiplexing MCP de alta performance com economia massiva de contexto

Ver no GitHub
BomPluginScore · de 0 a 100

Gateway universal de MCP que multiplexa múltiplos servidores em uma única porta, reduzindo o consumo de tokens de contexto em ~95% através de Meta-MCP. Roteia requisições de ferramentas, recursos e prompts para servidores MCP backends e APIs REST, sem necessidade de construir novos servidores MCP.

Instalação

$npx convez-ai MikkoParkkola/mcp-gateway

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
90
Forks
18
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
v3.5.2
Issues abertas
34
Contribuidores
4

Casos de uso

  • Integrar dezenas de ferramentas sem carregar todas as definições em cada requisição
  • Reduzir consumo de tokens em aplicações com muitas capabilities
  • Rotear requisições entre múltiplos servidores MCP backends dinamicamente

Veredito

Ferramenta robusta e bem arquitetada para cenários de produção exigentes, com implementação segura em Rust (zero unsafe) e conformidade OWASP. Ideal para quem precisa gerenciar muitos servidores MCP sem degradação de performance.

README

A tradução para o português deste README ainda está na fila.

MCP Gateway

CI Crates.io Downloads Rust License unsafe forbidden dependency status Capabilities MCP Protocol OWASP Agentic AI Glama Quality Score Install in VS Code Install in Cursor

Give your AI access to every tool it needs -- without burning your context window or building MCP servers.

demo

Independent Reviews

  • Five MCP hot-reload tools compared -- Ruach Tov Collective's BPD-based comparison of mcp-gateway against four restart-focused alternatives. Includes a feature matrix and architectural analysis.
  • mcp-gateway deep dive -- Detailed walkthrough of the capability system, SHA-256 integrity pinning, and the v2.5-to-v2.9 development arc.

MCP Gateway sits between your AI client and your tools. Instead of loading hundreds of tool definitions into every request, the AI gets a compact Meta-MCP surface -- 14 tools minimum, 16 in the README benchmark scenario, 17 when webhook status is surfaced -- and discovers the right backend tool on demand.

Public quantitative claims in this README are sourced from docs/BENCHMARKS.md and the machine-readable benchmarks/public_claims.json, with CI checks to catch drift.

What MCP Gateway is / is not

MCP Gateway is a tool and capability gateway. It routes MCP tool/resource/prompt traffic to backend MCP servers and capability-backed REST APIs, and it can proxy MCP server-to-client requests like sampling/createMessage, elicitation/create, and roots/list back to the connected client over the existing gateway session.

MCP Gateway is not a general OpenAI/Anthropic chat completions or embeddings gateway. When a backend asks for sampling/createMessage, the connected client still performs the model call. The OpenAI-compatible prompt-cache helpers in the gateway exist only so gateway_invoke can preserve prompt_cache_key behavior for backends or capabilities that happen to call LLM APIs internally.

Why

The context window is the bottleneck. Every MCP tool you connect costs ~150 tokens of context overhead. Connect 20 servers with 100+ tools and you've burned 15,000 tokens before the conversation starts -- on tool definitions the AI probably won't use this turn.

Worse: context limits force you to choose which tools to connect. You leave tools out because they don't fit -- and your AI makes worse decisions because it can't reach the right data.

MCP Gateway removes that tradeoff entirely.

Without GatewayWith Gateway
Tools in contextEvery definition, every request16 Meta-MCP tools in the README benchmark (~1600 tokens)
Token overhead~15,000 tokens (100 tools)~1600 tokens -- 89% savings
Cost at scale~$0.22/request (Opus input)~$0.024/request -- $201 saved per 1K
Practical tool limit20-50 tools (context pressure)Unlimited -- discovered on demand
Connect a new REST APIBuild an MCP server (days)Drop a YAML file or import an OpenAPI spec (minutes)
Changing MCP configRestart AI session, lose contextRestart gateway (~8ms), session stays alive
When one tool breaksCascading failuresCircuit breakers isolate it

The base discovery quartet (gateway_list_servers, gateway_list_tools, gateway_search_tools, gateway_invoke) stays constant. The README benchmark scenario also surfaces stats, cost report, playbooks, profile controls, disabled-capability visibility, and reload for a 15-tool surface. Surfacing webhook status adds the 16th tool.

Why not...

AlternativeWhat it doesWhy MCP Gateway is different
Direct MCP connectionsEach server connected individuallyEvery tool definition loaded every request. 100 tools = 15K tokens burned. Gateway: a small fixed 13-16 tool surface instead of every backend tool.
Claude's ToolSearchBuilt-in deferred tool loadingOnly works with tools already configured. Gateway adds unlimited backends + REST APIs without MCP servers.
ArchestraCloud-hosted MCP registryRequires cloud account, sends data to third party. Gateway is local-only, zero external dependencies.
Kong / PortkeyGeneral API gatewaysNot MCP-aware. No meta-tool discovery, no tool search, no capability YAML system.
Building fewer MCP serversReduce tool count manuallyYou lose capabilities. Gateway lets you keep everything and pay the token cost of the compact Meta-MCP surface.

vs Anthropic MCP Tunnels

On 2026-05-19 Anthropic shipped Claude Managed Agents with self-hosted sandboxes (public beta) and MCP tunnels (research preview). MCP tunnels let a Claude agent reach a single MCP server inside a private network through one outbound connection from a lightweight gateway -- no inbound firewall rules, no public endpoint, encrypted end-to-end.

mcp-gateway and Anthropic's MCP tunnel sit at different layers and compose. The tunnel is reachability plumbing for one private MCP server. mcp-gateway is the aggregation, routing, capability-namespacing and observability layer across many MCP and REST backends. When both are deployed, mcp-gateway becomes the private MCP server that Anthropic's tunnel exposes -- one tunnel, one outbound connection, every backend behind it.

ConcernAnthropic MCP tunnelmcp-gatewayBoundary
Backend topologySingle MCP server per tunnel, exposed through one outbound connection (overview)N-backend aggregation: 110+ REST capabilities + multiple MCP backends behind a compact 14-16 tool Meta-MCP surface (src/gateway/, capabilities/*.yaml)Different primitive: 1-server reachability vs many-backend aggregation
Tool routingOpaque pass-through; the agent sees whatever tool list the tunneled server publishesCapability namespacing + dynamic gateway_search_tools / gateway_invoke discovery (src/gateway/); SHA-256 pinning per capability (src/capability/hash.rs)Different layer: transport reachability vs tool-surface curation and integrity
ObservabilityPer-tunnel session telemetry from Anthropic's sideUnified trace_id and cost-accounting across every backend invocation (src/cost_accounting/, src/gateway/)Scope distinction: per-tunnel session vs cross-backend trace correlation

Complementary, not a replacement. A team that wants Claude Managed Agents to reach a private-network deployment of mcp-gateway uses the tunnel for reachability and mcp-gateway for fan-out, capability hygiene, OWASP Agentic AI controls (docs/OWASP_AGENTIC_AI_COMPLIANCE.md), and unified cost / trace telemetry. The two solve adjacent problems.

Security

Connecting N MCP servers to an agent means accepting N attack surfaces. Tool poisoning, rug pulls, and exfiltration via hidden instructions in tool descriptions are demonstrated attacks, not hypotheticals. Invariant Labs' writeup (MCP Security Notification: Tool Poisoning Attacks) and Simon Willison's summary (MCP has prompt injection security problems) lay out the threat model.

mcp-gateway puts every backend tool description behind one audit surface and defends it structurally:

  • Tool-poisoning validator (AX-010). Every backend tool description is scanned before it reaches the agent's context window. HIGH patterns fail-closed: <IMPORTANT> blocks, ~/.ssh/~/.aws/id_rsa/.env//etc/passwd, sidenote exfiltration language, curl .* https?://, base64 in exfil context. MEDIUM patterns warn: 40+ consecutive spaces, zero-width / bidi-override Unicode, oversized descriptions. Implementation: src/validator/rules/tool_poisoning.rs (19 tests).
  • SHA-256 capability hash-pinning. mcp-gateway cap pin <file> writes a sha256: line over the file's canonical hash (grep -v '^sha256:' capability.yaml | sha256sum is reproducible from any shell). The loader refuses any mismatched file on load and on every watcher event.
  • Rug-pull detection. When a pinned capability's on-disk content changes after approval, the watcher unloads it and logs RUG-PULL DETECTED. The capability stays quarantined until an operator re-pins. Implementation: src/capability/hash.rs and detect_rug_pulls in src/capability/backend.rs.
  • Centralized audit surface. Capability YAMLs are plain text, diffable, grep-able, PR-reviewable. The agent only ever sees the compact Meta-MCP surface (13-16 tools). No N-server tool-list pollution means no N-server attack surface.

Full walkthrough, PoC snippets, and roadmap: docs/blog/security-aware-mcp-gateway.md.

  • OWASP Agentic AI Top 10. Controls are mapped across all 10 risks, with explicitly tracked partial/out-of-scope gaps for multi-gateway signing, tool-result sandboxing, collusion detection, and remote-server provenance. See docs/OWASP_AGENTIC_AI_COMPLIANCE.md.

Recent additions

  • OpenAPI importer. mcp-gateway cap import <spec-url-or-file> turns an OpenAPI 3 spec into one validated capability YAML per operation. The full Swagger Petstore spec becomes 19 validated capability YAMLs end-to-end:
    mcp-gateway cap import https://petstore3.swagger.io/api/v3/openapi.json --output capabilities/ --prefix petstore
    
    22 tests across src/capability/openapi.rs and tests/openapi_import_tests.rs.

Quick Start

Tell your AI assistant (recommended):

Read https://github.com/MikkoParkkola/mcp-gateway and install mcp-gateway to consolidate all my MCP servers behind one gateway

Your agent will install the binary, run the setup wizard, import your existing MCP servers, and wire itself up. Works in Claude Code, Cursor, Windsurf, Codex, and any AI with terminal access.

Or four commands:

brew install MikkoParkkola/tap/mcp-gateway   # 1. install
mcp-gateway setup wizard --configure-client  # 2. import existing servers + wire up clients
mcp-gateway serve                            # 3. run
mcp-gateway doctor                           # 4. verify everything is healthy

That's it. Your AI clients now talk to the gateway and the gateway routes to every backend you already had configured — at a flat ~15 tools instead of ~150. Start with gateway_search_tools from your AI client to find any backend tool, then invoke it with gateway_invoke.

Nothing to import yet? mcp-gateway init --with-examples writes a working gateway.yaml with public capabilities so you can confirm the gateway is alive before adding your own servers.

Install

MethodCommand
Homebrew (macOS/Linux, recommended)brew install MikkoParkkola/tap/mcp-gateway
Cargocargo install mcp-gateway
cargo-binstallcargo binstall mcp-gateway
Direct binary download (Windows x64)Download mcp-gateway-windows-x86_64.exe from the latest release
Dockerdocker run -v $(pwd)/gateway.yaml:/config.yaml ghcr.io/mikkoparkkola/mcp-gateway:latest --config /config.yaml
# macOS Apple Silicon
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-arm64 -o mcp-gateway && chmod +x mcp-gateway

# macOS Intel
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-x86_64 -o mcp-gateway && chmod +x mcp-gateway

# Linux x86_64
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-linux-x86_64 -o mcp-gateway && chmod +x mcp-gateway
# Windows x64 (PowerShell)
Invoke-WebRequest -Uri https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-windows-x86_64.exe -OutFile mcp-gateway.exe

Set up — three ways

Option A — Auto-import everything (recommended)

mcp-gateway setup wizard --configure-client

Scans Claude Desktop, Claude Code, Cursor, Zed, Continue.dev, Codex, and running MCP processes; lets you pick which servers to import into gateway.yaml; and writes the gateway entry back into each detected client config so they route through the gateway instead. Add --yes to skip the prompts and import everything.

Option B — Add servers from the built-in registry

48 popular MCP servers are pre-registered with the right command, args, and env-var template. mcp-gateway add is claude mcp add / codex mcp add compatible:

mcp-gateway add tavily                                       # known server, fills env vars
mcp-gateway add my-server -- npx -y @some/mcp-server --flag  # arbitrary stdio command
mcp-gateway add --url https://mcp.sentry.dev/mcp sentry      # HTTP server
mcp-gateway add -e API_KEY=xxx my-server -- npx my-mcp-server

mcp-gateway list shows what's configured. mcp-gateway remove <name> removes one.

Option C — Hand-write gateway.yaml

For the full schema reference, see docs/QUICKSTART.md#configuration. Minimal example:

server:
  port: 39400

meta_mcp:
  enabled: true

backends:
  tavily:
    command: "npx -y @anthropic/mcp-server-tavily"
    description: "Web search"
    env:
      TAVILY_API_KEY: "${TAVILY_API_KEY}"

  sentry:
    http_url: "https://mcp.sentry.dev/mcp"
    description: "Sentry issues"

Run and verify

mcp-gateway serve                  # start the gateway
mcp-gateway doctor                 # diagnose config, port, env vars, backend health
mcp-gateway doctor --fix           # auto-fix issues where possible

The web dashboard is at http://localhost:39400/ui once serve is running.

Connect AI clients (if you skipped Option A)

setup export writes the gateway entry into client config files for you. It auto-detects the right path per client:

mcp-gateway setup export --target all                 # all detected clients
mcp-gateway setup export --target claude-code         # one client
mcp-gateway setup export --target all --dry-run       # preview without writing
mcp-gateway setup export --target all --watch         # regenerate on gateway.yaml changes
ClientConfig path
claude-code~/.claude.json
claude-desktopplatform-specific
cursor.cursor/mcp.json (workspace)
vs-code-copilot.vscode/mcp.json (workspace)
windsurf~/.codeium/windsurf/mcp_config.json
cline.cline/mcp_servers.json (workspace)
zed~/.config/zed/settings.json

Modes: --mode proxy (HTTP), --mode stdio (subprocess), --mode auto (probe health endpoint, fall back).

{
  "mcpServers": {
    "gateway": {
      "type": "http",
      "url": "http://localhost:39400/mcp"
    }
  }
}

Key Benefits

1. Unlimited Tools, Minimal Tokens

The gateway exposes 14 Meta-MCP tools minimum, 16 in the README benchmark scenario, and 17 when webhook status is surfaced. The base discovery quartet stays fixed; the rest are operator helpers for stats, cost, playbooks, profile control, disabled-capability visibility, reload, and webhook status.

Token math (Claude Opus @ $15/M input tokens, reproducible via python benchmarks/token_savings.py --scenario readme):

  • Without: 100 tools x 150 tokens x 1,000 requests = 15M tokens = $225
  • With (README benchmark): 16 Meta-MCP tools x 100 tokens x 1,000 requests = 1.6M tokens = $24.00

2. Any REST API to MCP Tool -- No Code

Turn any REST API into a tool by dropping a YAML file (~30 seconds) or importing an OpenAPI spec:

mcp-gateway cap import stripe-openapi.yaml --output capabilities/ --prefix stripe

The gateway ships with 110+ built-in capabilities -- weather, Wikipedia, GitHub, stock quotes, package tracking, and more. Capability YAMLs hot-reload automatically after file changes, no restart needed.

HeyGen video connector

mcp-gateway now ships HeyGen video-generation capabilities in capabilities/media/:

  • video_agent_create
  • video_create
  • video_get
  • video_download
  • voice_list
  • avatar_list

Setup:

export HEYGEN_API_KEY=your-api-key

Make sure your config loads the built-in capability directory:

capabilities:
  enabled: true
  directories:
    - ./capabilities

The request schemas ship hand-written for the initial connector, but HeyGen's CLI can act as the schema source of truth for future regeneration:

heygen video-agent create --request-schema
heygen video create --request-schema

Map that JSON into each capability's schema.input block when refreshing the connector.

Example end-to-end workflow:

# 1. Create the video with the Video Agent
CREATE=$(curl -s http://127.0.0.1:39401/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{
      "name":"gateway_invoke",
      "arguments":{
        "backend":"capabilities",
        "tool":"video_agent_create",
        "args":{"prompt":"A presenter explaining our product launch in 30 seconds"}
      }
    }
  }')

VIDEO_ID=$(printf '%s' "$CREATE" | jq -r '.result.content[0].text | fromjson | (.data.video_id // .video_id)')

# 2. Poll until completed and fetch the downloadable URL
VIDEO_URL=$(while true; do
  BODY=$(curl -s http://127.0.0.1:39401/mcp \
    -H 'Content-Type: application/json' \
    -d "{
      \"jsonrpc\":\"2.0\",
      \"id\":1,
      \"method\":\"tools/call\",
      \"params\":{
        \"name\":\"gateway_invoke\",
        \"arguments\":{
          \"backend\":\"capabilities\",
          \"tool\":\"video_get\",
          \"args\":{\"video_id\":\"$VIDEO_ID\"}
        }
      }
    }")
  STATUS=$(printf '%s' "$BODY" | jq -r '.result.content[0].text | fromjson | (.data.status // .status)')
  if [ "$STATUS" = "completed" ]; then
    printf '%s' "$BODY" | jq -r '.result.content[0].text | fromjson | (.data.video_url // .video_url)'
    break
  fi
  sleep 5
done)

# 3. Download and save a local MP4
curl -s http://127.0.0.1:39401/mcp \
  -H 'Content-Type: application/json' \
  -d "{
    \"jsonrpc\":\"2.0\",
    \"id\":1,
    \"method\":\"tools/call\",
    \"params\":{
      \"name\":\"gateway_invoke\",
      \"arguments\":{
        \"backend\":\"capabilities\",
        \"tool\":\"video_download\",
        \"args\":{\"video_url\":\"$VIDEO_URL\"}
      }
    }
  }" \
| jq -r '.result.content[0].text | fromjson | .data' \
| base64 --decode > heygen-explainer.mp4

3. Change Your MCP Stack Without Losing Your AI Session

Your AI connects once to localhost:39400. Behind it, capability YAMLs plus reloadable gateway config sections (including backend add/remove/update and routing/profile changes) can reload live via file watching, gateway_reload_config, or POST /ui/api/reload. Listener address changes report restart_required; env_files list changes stay startup-only and take effect after restart. Your AI session stays connected.

4. Production Resilience

Circuit breakers, retry with backoff, rate limiting, health checks, graceful shutdown, and concurrency limits. One flaky server won't take down your toolchain.

Architecture

┌───────────────────────────────────────────────────────────────┐
│                    MCP Gateway (:39400)                        │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  Meta-MCP: 13-16 Tools + Surfaced Tools                 │  │
│  │  • gateway_list_servers    • gateway_search_tools       │  │
│  │  • gateway_list_tools      • gateway_invoke             │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  Failsafes: Circuit Breaker │ Retry │ Rate Limit        │  │
│  └─────────────────────────────────────────────────────────┘  │
│                            │                                  │
│         ┌──────────────────┼──────────────────┐               │
│         ▼                  ▼                  ▼               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐       │
│  │   Tavily    │    │  Context7   │    │   Pieces    │       │
│  │   (stdio)   │    │   (http)    │    │   (sse)     │       │
│  └─────────────┘    └─────────────┘    └─────────────┘       │
└───────────────────────────────────────────────────────────────┘

Features

Web Dashboard

Embedded web UI at /ui -- live status, searchable tools, server health, config viewer. Operator dashboard at /dashboard. Cost tracking at /ui#costs. All served from the same binary and port, no frontend build step.

Security & Governance

FeatureDescriptionDocs
AuthenticationBearer tokens, API keys, explicit admin keys, per-client rate limits and opt-in per-client circuit breakersexamples/per-client-tool-scopes.yaml
Per-Client Tool ScopesAllowlist/denylist tools per API key with glob patternsexamples/per-client-tool-scopes.yaml
Security FirewallCredential redaction, prompt injection detection, shell/SQL/path traversal scanningCHANGELOG
Cost GovernancePer-tool, per-key, daily budgets with alert thresholds (log/notify/block)CHANGELOG
Session SandboxingPer-session call limits, duration caps, backend restrictionsCHANGELOG
mTLSCertificate-based auth for tool executionCHANGELOG

Integration & Discovery

FeatureDescription
Capability SystemREST API to MCP tool via YAML. Hot-reloaded. 110+ built-in. OpenAPI import supported.
Transform ChainsNamespace, filter, rename, and response transforms. Example.
WebhooksGitHub/Linear/Stripe push events as MCP notifications. Docs.
Auto-DiscoveryDiscover MCP servers from existing client configs and running processes.
Surfaced ToolsPin high-value tools directly in tools/list for one-hop invocation.
Semantic SearchTF-IDF ranked search across all tool names and descriptions.
Tool ProfilesUsage analytics per tool: latency, errors, trends. Persisted to disk.
Config ExportExport sanitized config as YAML/JSON. mcp-gateway config export

Protocol & Transport

  • MCP Version: 2025-11-25 (latest spec)
  • Transports: stdio, Streamable HTTP, SSE, WebSocket
  • Hot Reload: Capability YAMLs plus reloadable gateway config sections are watched and reloaded live
  • Reload Outcomes: gateway_reload_config and /ui/api/reload return restart_required for listener changes (for example server.host / server.port); env_files list edits remain startup-only
  • Config Discovery: Auto-finds gateway.yaml in cwd, ~/.config/mcp-gateway/, /etc/mcp-gateway/
  • "Did You Mean?": Levenshtein-based typo correction on tool names
  • Tool Annotations: MCP 2025-11-25 title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint; gateway meta-tools are fully annotated, while backend tools use the hybrid pass-through/fill policy in ADR-003
  • Dynamic Descriptions: Live tool/server counts in meta-tool descriptions
  • Tunnel Mode: Expose via Tailscale or pipenet without opening ports
  • Shell Completions: mcp-gateway completions bash|zsh|fish
  • Spec Preview (opt-in): Filtered tools/list (SEP-1821), tools/resolve (SEP-1862), dynamic promotion

Supported Backends

Any MCP-compliant server works. All three transport types supported:

TransportExamples
stdio@anthropic/mcp-server-tavily, @modelcontextprotocol/server-filesystem, @modelcontextprotocol/server-github
HTTPAny Streamable HTTP server
SSEPieces, LangChain, GitMCP (free remote docs+code search for any GitHub repo)

Remote MCP servers plug in by URL — no extra code. See examples/gateway-full.yaml for a commented GitMCP backend entry and docs/REMOTE_BACKENDS.md for a step-by-step walkthrough.

API

EndpointMethodDescription
/healthGETHealth check with backend status
/mcpPOSTMeta-MCP mode (dynamic discovery)
/mcp/{backend}POSTDirect backend access
/uiGETWeb dashboard
/dashboardGETOperator dashboard
/metricsGETPrometheus metrics (with --features metrics)

Performance

MetricValueNotes
Startup time~8msMeasured with hyperfine (benchmarks)
Binary size~12-13 MBRelease build with LTO, stripped
Hot-path microbenchmarksIncludedCriterion suite covers registry, parsing, cache-key, firewall, and semantic search hot paths
End-to-end latencyBackend-dependentMeasure with your real MCP servers and REST APIs rather than relying on a synthetic single number

SKILL.md / agentskills.io compatibility

MCP Gateway can ingest Agent Skills / Claude Code SKILL.md files and expose them as discoverable skills alongside capability YAML. This lets the gateway consume any SKILL.md — whether authored locally, shipped from agentskills.io, or pulled from a GitHub release — and surface it through the same meta-tool surface used for capabilities.

# Import a local skill directory (auto-discovers SKILL.md + resources/)
mcp-gateway skills import ~/.claude/skills/gws-gmail-send

# Import a single SKILL.md file
mcp-gateway skills import ./path/to/SKILL.md

# Import from an agentskills.io URL
mcp-gateway skills import https://agentskills.io/skills/my-skill/SKILL.md

# List imported skills
mcp-gateway skills list

# Search by name, description, trigger, or keyword
mcp-gateway skills search "gmail"

# Show the full body (including any embedded code blocks)
mcp-gateway skills show gws-gmail-send

# Remove a skill
mcp-gateway skills remove gws-gmail-send

What gets parsed

  • YAML frontmatter (name, description, version, effort, allowed-tools, triggers, keywords)
  • Markdown body, with fenced bash/python/json code blocks extracted as structured SkillCodeBlock entries
  • Progressive-disclosure resources: SKILL.advanced.md, reference.md, README.md, and any resources/*.md files in the skill directory

Security model (read-only)

Imported skills are stored as data, not executed. Embedded bash or python blocks are parsed and surfaced to users/agents via skills show, but MCP Gateway will never run them automatically. A future release may add opt-in execution gated on per-skill user consent. If you need to run a skill's commands today, copy them from skills show and run them in your own shell.

Registry location: ~/.mcp-gateway/skills.json (override with MCP_GATEWAY_SKILLS_REGISTRY or --registry).

Reference: Anthropic SKILL.md spec · agentskills.io

Documentation

DocumentContents
Quick StartZero to running in 2 minutes
Configuration ReferenceAll config options
OAuth ConfigurationOAuth 2.0 setup with Slack and Figma examples
Deployment GuideDocker, systemd, TLS/mTLS, scaling
OpenAPI ImportGenerate capabilities from OpenAPI specs
WebhooksEvent integration setup
Community RegistryShare and install capabilities
BenchmarksPerformance measurements
ChangelogRelease history
OWASP Agentic AI ComplianceRisk coverage matrix
vs Anthropic MCP TunnelsWhere mcp-gateway and Anthropic's MCP tunnel compose (different layers, complementary)

Troubleshooting

Backend won't connect? Test the command directly (npx -y @anthropic/mcp-server-tavily), then check gateway logs with --log-level debug.

Circuit breaker open? Check curl localhost:39400/health | jq '.backends'. Adjust thresholds in failsafe.circuit_breaker.

Tools not appearing? Verify the backend is running (gateway_list_servers). Tool lists are cached for 5 minutes.

Contributing

  1. Fork and branch (git checkout -b feature/your-feature)
  2. Test (cargo test) and lint (cargo fmt && cargo clippy -- -D warnings)
  3. PR against main with a clear description and CHANGELOG entry

See CONTRIBUTING.md for full details. Look for good first issue or help wanted to get started.

Ecosystem

mcp-gateway is part of a suite of MCP tools:

ToolDescription
mcp-gatewayUniversal MCP gateway — compact 13-16 tool surface replaces 100+ registrations
trvlAI travel agent — 36 MCP tools for flights, hotels, ground transport
nabWeb content extraction — fetch any URL with cookies + anti-bot bypass
axterminatormacOS GUI automation — 34 MCP tools via Accessibility API

License

mcp-gateway is dual-licensed as of v2.11.0:

ScopeLicenseFile
Core gateway, capabilities, transport, CLI, and everything not listed belowMITLICENSE
Designated Enterprise Edition modules (see below)PolyForm Noncommercial 1.0.0LICENSE-EE.md

EE-designated paths (every file carries // SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0):

  • src/security/firewall/ — egress filtering
  • src/security/agent_identity.rs — identity-based access control (OWASP ASI03)
  • src/security/data_flow.rs — data flow tracking (EU AI Act Art. 12)
  • src/security/message_signing.rs — HMAC inter-agent signing (OWASP ASI07)
  • src/security/policy.rs — advanced policy enforcement
  • src/security/response_inspect.rs, response_scanner.rs — outbound credential / exfil detection
  • src/security/scope_collision.rs — scope conflict detection
  • src/security/tool_integrity.rs — tool poisoning detection (OWASP ASI04)
  • src/cost_accounting/ — cost governance
  • src/key_server/ — OIDC-backed scoped key issuance

What this means in practice:

  • Free for noncommercial use, modification, redistribution.
  • Commercial use of EE modules requires a separate commercial license.
  • Companies can buy a standard commercial-use license via GitHub Sponsors at EUR 500/month per named project.
  • See COMMERCIAL.md for business use, forks, wrappers, shared services, and managed-service deployments.
  • All releases prior to v2.11.0 remain entirely MIT and stay MIT forever.

Credits

Created by Mikko Parkkola. Implements Model Context Protocol version 2025-11-25.

Changelog | Releases

Ver o original no GitHub

Bom para

Relacionados