mcp

command
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 14, 2026 License: Apache-2.0 Imports: 54 Imported by: 0

README

VaultRun MCP Server

Model Context Protocol server that exposes all VaultRun capabilities as tools. Works with Claude Desktop, Claude Code, OpenAI, OpenRouter, and any MCP-compatible platform.

70 tools · stdio + HTTP transports · AWS · databases · GitHub CI · Flowd (opt-in)

Build

go build -o vaultrun-mcp ./sdk/mcp/
# or install globally:
go install github.com/nickvd7/vaultrun/sdk/mcp@latest

Quick start

Claude Desktop / Claude Code (stdio)

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vaultrun": {
      "command": "/path/to/vaultrun-mcp",
      "env": {
        "VAULTRUN_BASE_URL": "http://localhost:8080",
        "VAULTRUN_API_KEY": "vr_yourkeyhere"
      }
    }
  }
}

Or via Claude Code CLI:

claude mcp add vaultrun /path/to/vaultrun-mcp \
  -e VAULTRUN_BASE_URL=http://localhost:8080 \
  -e VAULTRUN_API_KEY=vr_yourkeyhere
OpenAI / OpenRouter / any HTTP client
MCP_TRANSPORT=http \
MCP_AUTH_TOKEN=your-secret-token \
VAULTRUN_BASE_URL=http://localhost:8080 \
VAULTRUN_API_KEY=vr_yourkeyhere \
./vaultrun-mcp

# Endpoint: POST http://localhost:8090/mcp
# Header:   Authorization: Bearer your-secret-token
# Body:     {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{...}}
#
# MCP 2026-07-28 clients also send:
#   MCP-Protocol-Version: 2026-07-28
#   Mcp-Method: tools/call
#   Mcp-Name: <tool name>
# Legacy clients (no those headers) remain supported.

Protocol

  • SDK: official github.com/modelcontextprotocol/go-sdk v1.7.0+
  • Current: MCP 2026-07-28 (stateless Streamable HTTP)
  • Extensions: Tasks (async=true → get_task / update_task / cancel_task tools, plus tasks/* methods; optional Redis via MCP_REDIS_ADDR/REDIS_ADDR; caps via MCP_TASK_*), MCP Apps (ui://vaultrun/session-panel)
  • Auth (HTTP): static MCP_AUTH_TOKEN; optional OAuth PRM via MCP_OAUTH_ISSUERS (+ introspection)
  • Details: docs/mcp.md

Environment variables

Required (all transports)
Variable Description
VAULTRUN_BASE_URL Base URL of the VaultRun API
VAULTRUN_API_KEY VaultRun API key
Optional (all transports)
Variable Default Description
VAULTRUN_DEFAULT_IMAGE python:3.12-slim Default Docker image for new sessions
VAULTRUN_LOG_FILE stderr Write server logs to this file
GITHUB_TOKEN — GitHub PAT — required for run_github_repo and github_post_comment
MCP_FS_ALLOWED_PATHS — Comma-separated absolute paths for filesystem tools. Filesystem tools are disabled when unset.
MCP_AWS_ENABLED false Set true to activate all AWS tools. Explicit opt-in prevents accidental activation in EC2/ECS with instance roles.
AWS_REGION us-east-1 AWS region
AWS_ACCESS_KEY_ID — Static credentials (falls back to IAM role / env chain)
AWS_SECRET_ACCESS_KEY — Required when AWS_ACCESS_KEY_ID is set
AWS_ENDPOINT_URL — Custom endpoint for MinIO / LocalStack
MCP_S3_FORCE_PATH_STYLE false Path-style S3 addressing (needed for MinIO)
MCP_SQLITE_PATH — Path to a SQLite database file
MCP_PG_DSN — PostgreSQL DSN, e.g. postgres://user:pass@host/db
MCP_MONGO_URI — MongoDB URI, e.g. mongodb://localhost:27017
MCP_MONGO_DB test MongoDB database name
HTTP transport only (MCP_TRANSPORT=http)
Variable Default Description
MCP_AUTH_TOKEN — Bearer token (required — server refuses to start without it)
MCP_PORT :8090 Listen address
MCP_ALLOWED_ORIGINS * CORS allowed origins (comma-separated list for production)
MCP_RATE_LIMIT 60 Requests per minute per IP
MCP_TRUSTED_PROXIES — CIDRs of trusted reverse proxies
MCP_TLS_CERT — Path to TLS certificate (PEM)
MCP_TLS_KEY — Path to TLS private key (PEM)
MCP_ACME_DOMAIN — Domain for automatic Let's Encrypt TLS
MCP_ACME_CACHE_DIR — Directory for ACME challenge cache
MCP_ACME_EMAIL — Contact email for ACME registration
MCP_FLOWD_ENABLED false Set true to expose 6 flowd_* tools via local flowctl
FLOWCTL_PATH flowctl Path to flowctl binary
FLOWD_CONFIG — Optional config file for flowctl (--config)

All tools

Core: 53 tools. With MCP_FLOWD_ENABLED=true: 59 tools.

Sandbox (13 tools)
Tool Required params Description
create_session — Create an isolated Docker sandbox. Returns session_id.
list_sessions — List all active sessions.
get_session session_id Get session details (status, image, resource limits).
delete_session session_id Delete session, container, and workspace.
run_command session_id, command Execute a command inside the sandbox.
upload_file session_id, path, content Write a file into the sandbox workspace.
read_file session_id, path Read a file from the sandbox workspace.
list_files session_id List files in the sandbox workspace.
delete_file session_id, path Delete a file from the sandbox workspace.
get_run run_id Get run details (stdout, stderr, exit code, duration).
list_runs session_id List all command runs for a session.
get_session_stats session_id Get CPU and memory usage for a session.
get_session_logs session_id Get container logs (stdout + stderr stream).
Docker images (2 tools)
Tool Required params Description
list_images — List available Docker images on the host.
pull_image image Pull a Docker image from the registry.
Snapshots (2 tools)
Tool Required params Description
create_snapshot session_id, name Save the current workspace state as a named snapshot.
list_snapshots session_id List snapshots for a session.
Artifacts & audit (3 tools)
Tool Required params Description
create_artifact session_id, file_path, name Publish a file as a shared artifact (S3 or local).
list_artifacts — List all shared artifacts.
list_audit_logs — Browse the HMAC-signed audit log. Supports session_id, actor, action, limit.
GitHub (2 tools)

Requires GITHUB_TOKEN env var.

Tool Required params Description
run_github_repo owner, repo Clone a GitHub repo into a session and run a command. Uses http.extraheader — token never in URL.
github_post_comment owner, repo, number, body Post a comment on a GitHub issue or pull request.
Filesystem (4 tools)

Requires MCP_FS_ALLOWED_PATHS to be set. All paths are validated against the allowlist.

Tool Required params Description
fs_read_file path Read a file from the server filesystem.
fs_write_file path, content Write a file to the server filesystem.
fs_list_dir path List directory contents on the server filesystem.
fs_delete_file path Delete a file from the server filesystem.
AWS — S3 (6 tools)

Requires MCP_AWS_ENABLED=true.

Tool Required params Description
s3_list_buckets — List S3 buckets in the account.
s3_list_objects bucket List objects in a bucket. Optional: prefix, max_keys.
s3_get_object bucket, key Download an S3 object (max 10 MB, base64 for binary).
s3_put_object bucket, key, body Upload a string or base64-encoded object to S3.
s3_delete_object bucket, key Delete an S3 object.
s3_head_object bucket, key Get metadata for an S3 object without downloading.
AWS — SSM Parameter Store (4 tools)

Requires MCP_AWS_ENABLED=true.

Tool Required params Description
ssm_get_parameter name Get a parameter. SecureString values require with_decryption=true.
ssm_put_parameter name, value Create or update a parameter. Optional: type (String/SecureString/StringList).
ssm_delete_parameter name Delete a parameter.
ssm_list_parameters — List parameters. Optional: path prefix, max_results.
AWS — Secrets Manager (2 tools)

Requires MCP_AWS_ENABLED=true. sm_get_secret is in the write rate-limit tier and its result is redacted from audit logs.

Tool Required params Description
sm_get_secret secret_id Retrieve a secret value.
sm_list_secrets — List secret metadata (names only, no values).
AWS — Lambda (2 tools)

Requires MCP_AWS_ENABLED=true. lambda_invoke is in the heavy rate-limit tier (max 6 MB payload).

Tool Required params Description
lambda_list_functions — List Lambda functions in the configured region.
lambda_invoke function_name Invoke a Lambda function. Optional: payload (JSON), invocation_type.
SQLite (3 tools)

Requires MCP_SQLITE_PATH.

Tool Required params Description
sqlite_query query Run a read-only SQL query (SELECT, PRAGMA). Returns formatted rows.
sqlite_execute statement Execute a write statement (INSERT/UPDATE/DELETE/DDL). Returns rows affected.
sqlite_schema — Return DDL (CREATE TABLE) for all or a specific table.
PostgreSQL (3 tools)

Requires MCP_PG_DSN.

Tool Required params Description
pg_query query Run a read-only SQL query. Returns formatted rows.
pg_execute statement Execute a write statement. Returns rows affected.
pg_schema — Return column definitions from information_schema. Optional: table, schema (default public).
MongoDB (7 tools)

Requires MCP_MONGO_URI and MCP_MONGO_DB.

Tool Required params Description
mongo_find collection Find documents. Optional: filter (JSON), limit (1–1000, default 20).
mongo_insert_one collection, document Insert a single document (JSON).
mongo_update collection, update Update documents with an operator document ($set, etc.). Optional: filter, many=true.
mongo_delete collection Delete documents. Optional: filter, many=true.
mongo_aggregate collection, pipeline Run an aggregation pipeline (JSON array of stages).
mongo_collections — List all collection names in the database.
mongo_generate_mongoose collection Sample up to 50 documents and generate a Mongoose schema (JavaScript).
Flowd — local workflows (6 tools)

Requires MCP_FLOWD_ENABLED=true and flowctl on the same host as vaultrun-mcp. See docs/flowd-integration.md.

Tool Required params Description
flowd_list_suggestions — List pending workflow suggestions from flowd.
flowd_explain_suggestion — Explain suggestions. Optional: suggestion_id.
flowd_approve_suggestion suggestion_id Approve a suggestion by ID.
flowd_list_patterns — List detected workflow patterns.
flowd_stats — Local Flowd usage statistics.
flowd_undo_run run_id Undo a Flowd automation run.

Security model

  • No shell — all commands run through Docker exec API, never through a shell.
  • Non-root containers — all capabilities dropped, seccomp default profile applied.
  • Network off by default — network_enabled must be explicitly set to true.
  • Audit log — every tool call is logged with tool name, parameters, client IP, and duration. Sensitive results (sm_get_secret, ssm_get_parameter) are redacted.
  • Rate limiting — read tools: 60 req/min, write tools: 30 req/min, heavy tools (container creation, Lambda, GitHub clone): 10 req/min.
  • AWS opt-in — MCP_AWS_ENABLED=true prevents accidental IAM credential activation.
  • Flowd opt-in — MCP_FLOWD_ENABLED=true runs local flowctl; no network API in Flowd itself.
  • Filesystem allowlist — filesystem tools return an error when MCP_FS_ALLOWED_PATHS is not set; paths are validated against the allowlist with symlink resolution.
  • Token never in URL — GitHub clones use http.extraheader (Authorization: Bearer ...) so the token never appears in git remote URLs or log output.

HTTP transport endpoints

POST /mcp     JSON-RPC 2.0 request/response
GET  /sse     Server-Sent Events (future: streaming tool results)
GET  /        Server info JSON (name, version, transport, tool count)
GET  /healthz Health check — returns {"ok":true}

Security headers on every response: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Cache-Control: no-store.

Development

# Run all tests
go test ./sdk/mcp/... -v

# Run only DB tests (in-memory SQLite, no external services needed)
go test ./sdk/mcp/... -run TestSQLite -v

# Smoke-test HTTP transport
MCP_TRANSPORT=http MCP_AUTH_TOKEN=test \
VAULTRUN_BASE_URL=http://localhost:8080 VAULTRUN_API_KEY=vr_... \
./vaultrun-mcp &

curl -s -X POST http://localhost:8090/mcp \
  -H 'Authorization: Bearer test' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq '.result.tools | length'
# → 53 (59 with MCP_FLOWD_ENABLED=true)

# Without token → 401
curl -s -X POST http://localhost:8090/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq .
# → {"error":"unauthorized"}

Documentation

Overview

MCP Apps extension — server-rendered UI resources for hosts that support it.

AWS tools for the MCP server — S3 operations. All AWS clients share a single configuration loaded by initAWSClients.

Environment variables: 

AWS_REGION                  AWS region (default: us-east-1)
AWS_ACCESS_KEY_ID           Static access key (optional — falls back to IAM role)
AWS_SECRET_ACCESS_KEY       Static secret key (required when access key ID is set)
AWS_ENDPOINT_URL            Override endpoint URL (for MinIO, LocalStack, etc.)
MCP_S3_FORCE_PATH_STYLE     Use path-style S3 addressing (required for MinIO)

AWS Lambda tools for the MCP server.

AWS SSM Parameter Store and Secrets Manager tools for the MCP server.

Bridge between VaultRun tool handlers and the official MCP Go SDK.

Browser automation MCP tools

VaultRun API client used by the MCP server.

Database bundle — SQLite, PostgreSQL, and MongoDB clients for MCP tools.

MongoDB MCP tool handlers.

PostgreSQL MCP tool handlers.

SQLite MCP tool handlers.

Local filesystem tools for the MCP server. Access is gated by MCP_FS_ALLOWED_PATHS (comma-separated absolute paths).

Flowd tools for the MCP server — local workflow automation via flowctl.

Environment variables: 

MCP_FLOWD_ENABLED  Set to "true" to expose flowd_* tools (explicit opt-in)
FLOWCTL_PATH       Path to flowctl binary (default: flowctl)
FLOWD_CONFIG       Optional config file path passed as --config to flowctl

GitHub API client for the MCP server.

HTTP transport for the VaultRun MCP server. Activated by setting MCP_TRANSPORT=http.

Environment variables (HTTP transport only): 

MCP_PORT              Listen address (default: :8080, or :443 in ACME mode)
MCP_AUTH_TOKEN        Bearer token required on every request (required)
MCP_ACME_DOMAIN       Enable Let's Encrypt auto-TLS for this hostname
MCP_ACME_CACHE_DIR    Directory to cache ACME account keys and certs (default: /data/mcp-acme-cache)
MCP_ACME_EMAIL        Contact email for the ACME account (recommended; enables expiry notices)
MCP_TLS_CERT          Path to TLS certificate file (alternative to ACME)
MCP_TLS_KEY           Path to TLS private key file (alternative to ACME)
MCP_ALLOWED_ORIGINS   Comma-separated CORS origins (default: *)
MCP_TRUSTED_PROXIES   Comma-separated CIDRs/IPs of trusted reverse proxies.
                      When empty (default) X-Forwarded-For is NOT trusted and the
                      rate limiter keys on the real TCP peer address. Set this only
                      when running behind a known proxy, otherwise clients could
                      spoof their source IP to bypass per-IP rate limiting.
MCP_RATE_LIMIT        Max requests per minute per IP — global (default: 60)
MCP_RATE_LIMIT_WRITE  Additional per-IP limit for workspace-write tools like
                      upload_file and delete_file (default: MCP_RATE_LIMIT/2)
MCP_RATE_LIMIT_HEAVY  Additional per-IP limit for resource-creating tools like
                      run_command, create_session, create_snapshot, create_artifact
                      (default: MCP_RATE_LIMIT/3, minimum 1)

VaultRun MCP Server — exposes VaultRun sandbox capabilities as MCP tools.

Usage (stdio transport — default, for Claude Desktop/Code): 

VAULTRUN_BASE_URL=http://localhost:8080 \
VAULTRUN_API_KEY=vr_yourkeyhere \
./vaultrun-mcp

Usage (HTTP transport — for OpenAI, OpenRouter, and other platforms): 

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN=your-secret-token \
VAULTRUN_BASE_URL=http://localhost:8080 \
VAULTRUN_API_KEY=vr_yourkeyhere \
./vaultrun-mcp

Environment variables (all transports): 

VAULTRUN_BASE_URL        Base URL of the VaultRun API (required)
VAULTRUN_API_KEY         API key for authentication (required)
VAULTRUN_DEFAULT_IMAGE   Default Docker image for sessions (default: python:3.12-slim)
VAULTRUN_LOG_FILE        Write server logs to this file instead of stderr
MCP_TRANSPORT            Transport to use: "stdio" (default) or "http"
GITHUB_TOKEN             GitHub personal access token (optional). Required for
                         run_github_repo to clone private repos and for
                         github_post_comment to post to repos.
MCP_FS_ALLOWED_PATHS     Comma-separated list of absolute paths the filesystem
                         tools (fs_read_file, fs_write_file, fs_list_dir,
                         fs_delete_file) are allowed to access. When unset,
                         all filesystem tools return an error.
MCP_AWS_ENABLED          Set to "true" to enable all AWS tools (S3, SSM,
                         Secrets Manager, Lambda). Explicit opt-in prevents
                         accidental activation in environments with ambient
                         IAM credentials (EC2/ECS instance roles).
AWS_REGION               AWS region (default: us-east-1).
AWS_ACCESS_KEY_ID        Static access key (optional — falls back to IAM role).
AWS_SECRET_ACCESS_KEY    Static secret key (required when access key ID is set).
AWS_ENDPOINT_URL         Custom endpoint for MinIO, LocalStack, etc.
MCP_S3_FORCE_PATH_STYLE  Set to "true" for path-style S3 addressing (MinIO).

Additional environment variables for MCP_TRANSPORT=http (see http.go): 

MCP_AUTH_TOKEN, MCP_PORT, MCP_ALLOWED_ORIGINS, MCP_RATE_LIMIT
MCP_TRUSTED_PROXIES                  (CIDRs/IPs of trusted reverse proxies)
MCP_ACME_DOMAIN, MCP_ACME_CACHE_DIR, MCP_ACME_EMAIL  (Let's Encrypt auto-TLS)
MCP_TLS_CERT, MCP_TLS_KEY            (static cert, alternative to ACME)

Database environment variables (optional — any combination can be enabled): 

MCP_SQLITE_PATH  Absolute path to a SQLite database file.
MCP_PG_DSN       PostgreSQL connection string (e.g. "postgres://user:pass@host/db").
MCP_MONGO_URI    MongoDB connection URI (e.g. "mongodb://localhost:27017").
MCP_MONGO_DB     MongoDB database name (default: test). Required with MCP_MONGO_URI.

Flowd environment variables (optional — local workflow automation bridge): 

MCP_FLOWD_ENABLED  Set to "true" to expose flowd_* tools via local flowctl
FLOWCTL_PATH       Path to flowctl binary (default: flowctl)
FLOWD_CONFIG       Optional config file for flowctl (--config)

Agent memory tools — persistent key/value notes in the sandbox workspace under .vaultrun/memory/. Survives within a session and via workspace snapshots.

OAuth / protected-resource auth for the HTTP MCP transport.

Modes (HTTP only):

  1. Static bearer — MCP_AUTH_TOKEN (required fallback / primary for local use).
  2. OAuth Protected Resource Metadata — when MCP_OAUTH_ISSUERS is set, publish /.well-known/oauth-protected-resource so clients (including Enterprise Managed Authorization / EMA clients) can discover authorization servers.
  3. Optional RFC 7662 introspection — MCP_OAUTH_INTROSPECTION_URL (+ client id/secret) validates non-static bearer tokens against the IdP.

EMA is primarily a client flow (extauth.EnterpriseHandler). Server-side EMA support is: advertise PRM, validate tokens from the enterprise auth server.

MCP shared protocol types, server state, and helpers.

Production transports (stdio + HTTP) use the official Go MCP SDK — see bridge.go, main.go, and http.go.

Tasks extension (io.modelcontextprotocol/tasks, SEP-2663) — pollable long-running work.

The official Go SDK (v1.7.0) does not yet ship first-class Tasks support. See tasks_sdk_compat.go for the registration seam and migration checklist. VaultRun implements the extension surface via custom methods so clients that advertise the extension can poll durable task handles.

Persistence: in-memory by default. When REDIS_ADDR or MCP_REDIS_ADDR is set and reachable, task metadata is stored in Redis (survives restarts / shared across MCP instances). Cancel funcs stay process-local; cross-instance cancel uses Redis pub/sub.

Upstream Go SDK Tasks compatibility notes and registration boundary.

As of github.com/modelcontextprotocol/go-sdk v1.7.0 (still latest on proxy.golang.org as of 2026-08), the SDK speaks MCP 2026-07-28 and exposes AddReceivingCustomMethod, but it does NOT ship first-class helpers for the Tasks extension (io.modelcontextprotocol/tasks, SEP-2663): no Task types, no tasks/get|update|cancel registration helpers, and no built-in async tool result wrapping. Re-check on each go-sdk upgrade before migrating.

VaultRun therefore keeps a server-side implementation in tasks.go / tasks_input.go / tasks_redis.go and registers the wire methods through registerTaskMethods. When upstream adds Tasks support, migrate by:

  1. Prefer SDK-native registration / types if they cover get/update/cancel and CreateTaskResult (resultType:"task").
  2. Keep VaultRun persistence (memory/Redis), security caps, owner binding, and input_required/confirm behavior behind the same taskStore.
  3. Delete or narrow this file once the SDK path is the only registration surface and sdk_ext_test.go still passes.

Do not invent a parallel Tasks protocol here — this file is only the documented seam between VaultRun's store and the SDK custom-method API.

MCP tool definitions and dispatch.

MCP verify_checkpoint — evaluate post-run assertions (exit/stdout/file).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.