nuvel-mcp

A dependency-free MCP server that exposes a Nuvel skills hub (a directory of SKILL.md skills) to any MCP client. The default stdio transport needs nothing beyond the standard library.

# one-shot, no install
uvx nuvel-mcp serve --skills-dir /path/to/skills-hub

# or install it
pip install nuvel-mcp
nuvel-mcp serve --skills-dir /path/to/skills-hub

Run nuvel-mcp serve --help for all flags (--theme, --require, --with-org-memory, --feedback-dir, --tools, --trace-store, --transport, --host, --port, --allow-remote, --no-auth, --require-auth). Without --skills-dir the server starts in feedback-only mode.

State lives in files by default. Set NUVEL_MCP_DATABASE_URL (for example a Neon pooled connection string) and OAuth, run traces, recipes and a per-request usage log all go to Postgres instead; that needs pip install "psycopg[binary,pool]", and the package itself stays dependency-free. The schema is migrated at startup; nuvel-mcp db migrate|status|import manage it, and db import copies existing files in. See the deploy guide.

With a database, each request is logged for the operator: when, which OAuth client, method and tool name (known names only), outcome, error code, latency, the session's client app (initialize clientInfo name and version, sanitized to 64 safe characters) and, optionally, the caller's country. IP addresses, tool arguments and any other content are never stored. The country needs NUVEL_MCP_GEOIP_CSV pointing at the DB-IP "IP to Country Lite" CSV, which you download yourself (CC BY 4.0: credit "IP Geolocation by DB-IP"); turn it off with NUVEL_MCP_RECORD_COUNTRY=0. nuvel-mcp clients label|list records who is behind a client id, and nuvel-mcp report [--days 7] [--json] prints the usage report. Nothing is pruned automatically: delete old usage_events rows with SQL. See Usage insights for exactly what is collected and retention.

The HTTP transport (Streamable HTTP on /mcp, legacy SSE, OAuth 2.1) is part of the same dependency-free package; there are no extras. It binds 127.0.0.1:8080 and requires an OAuth token unless you pass --no-auth on a loopback bind. Create a client for a trace-recording workload and serve:

uvx nuvel-mcp client create --name acme-radar
uvx nuvel-mcp serve --transport http

client create prints a client_id and a client_secret (shown once). A workload exchanges them for an access token with the client_credentials grant, then sends it as a bearer token to /mcp. On the default loopback bind the server is http://127.0.0.1:8080; for a remote deployment use its public URL, $NUVEL_MCP_PUBLIC_URL, instead:

curl -s -u "$NUVEL_CLIENT_ID:$NUVEL_CLIENT_SECRET" \
  -d grant_type=client_credentials "http://127.0.0.1:8080/token"
# -> {"access_token": "...", ...}; call /mcp with
#    Authorization: Bearer $ACCESS_TOKEN

For an MCP client that can only be given a URL (a Claude custom connector with no sign-in), uvx nuvel-mcp client create --name alice --url-key prints a per-client connector_url ($NUVEL_MCP_PUBLIC_URL/mcp/k/<key>) once; add --expires-in DAYS for a key that stops working after that long. To rotate a key, issue a new one, hand it out, then client delete the old client. Set NUVEL_OAUTH_LOGIN=none to run a public server with no interactive login.

The deployment guide covers scopes and the interactive flow.

Over HTTP the default tools are the hub read tools plus record_run_trace, check_skill_health, record_recipe_signal and share_recipe; record_feedback, propose_improvement and install_skill are exposed only when named in --tools. The tenant of each run trace is the OAuth client_id.

See the deployment guide for TLS and what is exposed over HTTP.

Relationship to nuvel-cli

This package is released from the same monorepo as nuvel-cli at the same version. nuvel mcp serve delegates to nuvel-mcp, and the old nuvel.mcp import path is a deprecated shim; import nuvel_mcp instead.