vmcp MCP server
Commit Sep 19, 2026Aggregates multiple MCP servers into a single GraphQL endpoint to allow agents to perform complex queries in a single round trip.
Also known as hewimetall/vmcp
- Stars
- 13
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 19, 2026
- License
- MIT
What is vmcp MCP?
vmcp aggregates multiple MCP servers into a single GraphQL endpoint to allow agents to perform complex queries in a single round trip.
Summary generated from the project's README
About vmcp MCP server
vmcp acts as a gateway written in Rust that consolidates multiple upstream MCP servers into a single GraphQL endpoint. This architecture allows AI agents to execute complex queries through a single query_graphql tool call rather than performing numerous individual round trips. The system builds a dynamic schema at startup by reading the tools/list responses from connected servers, which can be added via HTTP or stdio transports.
Developers can deploy this service using Docker or by running the binary directly with a configuration file. It supports various authentication methods including OAuth 2.1 with PKCE and DCR, or static bearer tokens for continuous integration environments. For local development with clients like Claude Desktop or Cursor, the vmcp-lite component provides stdio support. The gateway also includes an operator API for managing tokens and reloading upstream servers without requiring a full restart.
What you can do with it
- 1Manage long-running operationsA developer can execute tools that require extended runtimes by utilizing the built-in task support.
- 2Automate server configurationYou can add new MCP servers to the gateway using command line utilities to automatically probe their tool specifications.
- 3Secure CI/CD pipelinesUse non-expiring bearer tokens to allow automated systems to access the MCP gateway without constant re-authentication.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
VMCP_AUTH__MASTER_PASSWORD_ARGON2
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehewimetall/vmcp is public and reachablegithub.com/hewimetall/vmcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-19github.com/hewimetall/vmcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubvmcp
Language: English | Русский
An MCP gateway written in Rust. It aggregates multiple upstream MCP servers behind a single GraphQL endpoint, allowing an agent to make one query_graphql call instead of many round trips.
Why vmcp
- One
query_graphqltool — send GraphQL and vmcp routes requests to the upstream servers. Reads run in parallel; writes run sequentially. - Dynamic schema — built at startup from upstream
tools/listresponses. - Tasks (optional) — run long-running tools as durable tasks backed by SQLite.
- OAuth 2.1 + PKCE + DCR — or static bearer tokens.
- Hot reload — tokens,
registry.json, and prompts update without a restart. - GCF output (optional) —
[gql].gcfforquery_graphql(/mcp) and[proxy].gcffor/mcp-proxy. Use GCF instead of JSON. /api/v1— operator API for token CRUD and upstream reloads (Bearermcp:admin).
Getting started
docker pull ghcr.io/hewimetall/vmcp:1.0.0
./deploy/bootstrap.sh --domain gateway.example.com --tag 1.0.0
Or run the binary directly:
curl -fsSL -o vmcp.tgz "https://github.com/hewimetall/vmcp/releases/download/v1.0.0/vmcp-1.0.0-linux-x86_64.tar.gz"
tar -xzf vmcp.tgz
./vmcp --config ./demo/vmcp.toml
The gateway listens on http://127.0.0.1:8765:
/mcp— MCP endpoint/health— liveness endpoint- OAuth endpoints (
/authorize,/token,/register, …) — authentication is disabled in the demo
Demo: demo/README.md.
Configuration
Edit vmcp.toml. Any key can be overridden with a VMCP_* environment variable; use __ for nested keys:
VMCP_AUTH__MASTER_PASSWORD_ARGON2='$argon2id$...' cargo run -p vmcp
# Advertise MCP 2026-07-28 (off by default): VMCP_MCP__LATEST=true
Utilities:
cargo run -p vmcp -- init
cargo run -p vmcp -- add mcp --transport http notion https://mcp.notion.com/mcp
cargo run -p vmcp -- add mcp --transport stdio time -- uvx mcp-server-time
# (probe tools/list → specs/<name>.json; offline: --no-spec)
cargo run -p vmcp -- add tool presentation build_presentation --task-support optional
cargo run -p vmcp -- add skill search_docs --description 'docs' --template 'Call query_graphql…'
cargo run -p vmcp -- add tasks
cargo run -p vmcp -- list mcp
cargo run -p vmcp -- list tool
cargo run -p vmcp -- hash-password --password 'secret'
cargo run -p vmcp -- print-config
Static tokens (for CI)
OAuth issues short-lived JWTs that become invalid after a restart. For CI and demos, use a non-expiring bearer token:
cargo run -p vmcp -- pre-reg --name ci --scope mcp:use --out ./tokens.json
# → vmcp_xK3v...
[auth]
tokens_file = "./tokens.json"
curl -H "Authorization: Bearer vmcp_xK3v..." http://127.0.0.1:8765/mcp
The file is hot-reloaded. Removing a line revokes that token. These are unrestricted tokens with no expiration, so store them as secrets.
Disable authentication (local use only)
auth.enabled = false removes bearer-token protection from /mcp and hides /admin. Never use this setting in production.
Local stdio (Claude Desktop, Cursor)
vmcp supports HTTP only. For stdio, use vmcp-lite:
{
"mcpServers": {
"vmcp-lite": {
"command": "uvx",
"args": ["vmcp-lite-mcp", "--config", "/path/to/vmcp.toml"]
}
}
}
Build
cargo build --release -p vmcp # + admin UI (default)
cargo build --release -p vmcp --no-default-features # without admin UI
Crates
| Crate | Purpose |
|---|---|
vmcp |
Entry-point binary (axum + rmcp). |
vmcp-config |
Configuration (figment + TOML + environment variables). |
vmcp-registry |
registry.json, specs, and lock file. |
vmcp-upstream |
Pool of upstream MCP clients. |
vmcp-graphql |
Dynamic GraphQL schema. |
vmcp-auth |
OAuth 2.1 + PKCE + DCR and JWKS. |
vmcp-server |
MCP surface, tasks, and skills. |
vmcp-notify |
Notification ring buffer. |
vmcp-admin |
Admin UI and recordings. |
vmcp-watch |
File watcher and hot reload. |
Documentation
See docs/README.md for the full guide to deployment, authentication, upstream servers, tasks, skills, and clients.
How-to guides:
License
MIT — see LICENSE.
vmcp MCP questions
How does vmcp handle multiple requests?
It uses a single query_graphql tool where reads are executed in parallel and writes are executed sequentially.
Does the schema update automatically?
Yes, the dynamic schema is built at startup from the tools/list responses of the upstream servers.
How can I run long-running tools?
You can run long-running tools as durable tasks backed by SQLite.