TokenHub MCP

TokenHub MCP is a production-packaged Model Context Protocol server for coding agents. It keeps the always-loaded MCP surface small, then routes larger file, git, web, database, package, browser, GitHub, and Sentry work through token-budgeted tools, workflows, and tokenhub://resource/... artifacts.

Install

Run without installing:

npx tokenhub-mcp --root /path/to/workspace

Install globally:

npm install -g tokenhub-mcp
tokenhub-mcp --root /path/to/workspace

For local development from this repository:

npm install
npm run build
node dist/cli.js --root /path/to/workspace

When serving the repository root itself during local development:

node dist/cli.js --root .

Quick Start

Start TokenHub with a workspace root that should bound filesystem and git operations:

npx tokenhub-mcp --root /path/to/workspace

Then call the public MCP tool run_workflow with an advertised workflow capability:

{
  "name": "resolve_request",
  "request": "Inspect this repository and summarize the main architecture, runtime stack, and entry points.",
  "depth": "standard",
  "evidence": "resource_links",
  "execution": "answer_only"
}

Large or raw outputs are returned as redacted tokenhub://resource/... handles. Use read_resource to expand snippets, ranges, or full resource content.

Documentation

The README is the quick production reference. The full project docs live under docs/:

| Document | Purpose | | --- | --- | | Docs index | Navigation for operators, contributors, and release owners. | | Architecture | Runtime layout, tool surface, workflows, resources, and package boundaries. | | Configuration | CLI flags, MCP client setup, provider inputs, and environment variables. | | Operations | Install, run, validate, smoke test, troubleshoot, and maintain the service. | | Security | Workspace confinement, mutation opt-in, credential handling, and network boundaries. | | Release | Release checklist, verification evidence, npm packaging contract, and rollback notes. |

Public release support files:

• CHANGELOG.md records user-facing changes by version.
• CONTRIBUTING.md explains local setup, testing, and contribution expectations.
• SECURITY.md explains how to report vulnerabilities and what versions are supported.
• CODE_OF_CONDUCT.md sets the baseline for community behavior.

MCP Client Configuration

Local package execution with npx:

{
  "mcpServers": {
    "tokenhub": {
      "command": "npx",
      "args": ["tokenhub-mcp", "--root", "/path/to/workspace"]
    }
  }
}

Global install:

{
  "mcpServers": {
    "tokenhub": {
      "command": "tokenhub-mcp",
      "args": ["--root", "/path/to/workspace"]
    }
  }
}

On Windows, quote paths in your MCP client JSON as a single JSON string, for example "C:\\Users\\you\\project".

Tools

TokenHub exposes exactly six public MCP tools:

| Tool | Production status | Purpose | | --- | --- | --- | | discover_capabilities | Production | Finds deferred internal capabilities without loading every schema into the client context. | | run_workflow | Production | Runs server-side workflows such as resolve_request, answer_from_web, validate, filesystem_action, git_action, and project_scan. | | retrieve_context | Production | Retrieves token-budgeted context from runtime sources including files, git, web pages, search, databases, GitHub, npm docs, Sentry, and browser state. | | read_resource | Production | Reads a tokenhub://resource/... artifact by snippet, line range, or full content. | | capture_state | Production | Stores caller-provided logs, snapshots, or state summaries as resource artifacts. | | estimate_cost | Production | Estimates tool cost, saved tokens, and whether the operation clears the default ROI threshold. |

The user-facing advertised capabilities in this README are resolve_request, answer_from_web, web_fetch, web_search, filesystem, and git. Those are not separate top-level MCP tools; they are workflows or retrieval capabilities reached through the six public tools above.

Workflows

| Workflow | Invoke through | Behavior | | --- | --- | --- | | resolve_request | run_workflow | Infers intent, source strategy, output shape, depth, evidence mode, and execution mode from a natural-language request. It supports answer_only and plan_only; implementation execution modes are rejected instead of faking success. | | answer_from_web | run_workflow | Searches the web, fetches source pages, extracts clean text, and returns cited ranked-list or summary answers with source resource links. | | validate | run_workflow | Runs allowlisted validation commands (npm test, npm run lint, or npm run build), redacts secret-looking output, stores the full validation log as a resource, and reports pass/fail warnings. | | filesystem_action | run_workflow | Lists a workspace tree by default. Write, move, and delete require the service process to be started with TOKENHUB_ENABLE_FS_MUTATIONS=true. | | git_action | run_workflow | Runs bounded git status, diff, show, stage, commit, or branch operations inside the configured workspace. | | project_scan | run_workflow | Combines git summary and filesystem search into compact project context. |

Example web answer:

{
  "name": "answer_from_web",
  "query": "top 10 healthiest vegetables",
  "target": "ranked_list",
  "limit": 10,
  "sourceLimit": 5
}

Validation example:

{
  "name": "validate",
  "command": "npm",
  "args": ["test"]
}

Unsupported workflow modes, including execution: "implement" and execution: "implement_and_verify" for resolve_request, return explicit errors rather than claiming a mutation happened.

Retrieval Sources

retrieve_context.source uses the runtime names shown below. The docs also name friendly advertised sources where they differ.

| Documented source | Runtime source | Required configuration | Supported operations | Optional-provider errors | | --- | --- | --- | --- | --- | | filesystem | files | --root; optional query, limit, budgetTokens | Search workspace files, return redacted snippets and resource links | Missing matches return empty results; workspace escape attempts are rejected. | | git | git | --root in a git repository | Summarize status, recent commits, diff stats, and raw log resource | Non-repositories return warnings instead of raw git floods. | | web / web_fetch | web | url | Fetch and scrape one web page with timeout and optional raw resource | Missing url errors; HTTP failures include status. | | web_search | search | query; optional provider and apiKey | Search Brave, Exa, Tavily, SerpAPI, or no-key DuckDuckGo fallback | Provider-specific modes error when the required API key is absent. | | github | github | owner and repo; optional token | Summarize repo, issues, PRs, and workflow runs | Missing owner/repo errors; private or rate-limited repos need a token. | | sqlite | sqlite | databaseBase64; optional read-only query | Inspect schema and safe SELECT rows | Missing database bytes errors; non-SELECT queries return warnings and no rows. | | postgres | postgres | connectionString; optional read-only query | Inspect public schema and safe SELECT rows | Missing connection string errors; auth/network failures come from pg. | | npm | docs | packageName or query | Fetch npm registry metadata, latest version, docs, repository, and releases link | Missing package/query errors; registry HTTP failures include status. | | sentry | sentry | issues array, or organization plus token; optional project | Summarize and cluster issue impact | Missing issues or organization/token errors; Sentry API HTTP failures include status. | | browser | browser | url; Playwright browser dependencies installed | Capture title, headings, links, form controls, console errors, failed requests, and optional screenshot | Missing URL errors; navigation timeout is currently 20000ms. |

Environment Variables

| Variable | Used for | | --- | --- | | BRAVE_SEARCH_API_KEY | Selects Brave as the default web_search provider and authenticates Brave Search. | | EXA_API_KEY | Selects Exa as the default search provider when Brave is not set. | | TAVILY_API_KEY | Selects Tavily as the default search provider when Brave and Exa are not set. | | SERPAPI_API_KEY | Selects SerpAPI as the default search provider when the other keyed providers are not set. | | TOKENHUB_ENABLE_FS_MUTATIONS | When set to true, enables trusted-local filesystem write, move, and delete workflows. Leave unset for read/list behavior. | | TOKENHUB_ALLOW_PRIVATE_NETWORK | When set to true, allows trusted-local web and browser retrieval of localhost, private LAN, and other non-public network targets. Leave unset for public-network-only retrieval. |

GitHub tokens are supplied as retrieve_context input token; there is no dedicated GitHub environment variable in the runtime. Sentry tokens are supplied as token, Postgres uses connectionString, npm registry lookup uses the public registry URL, and browser capture uses local Playwright without a credential variable. Network timeouts are currently fixed in code: web fetch and DuckDuckGo search use 5000ms, browser navigation uses 20000ms, git commands use 10000ms, and validation commands use 120000ms.

Security Notes

TokenHub confines filesystem paths to the configured --root workspace and rejects path escapes, including symlink-realpath escapes for mutation targets. File snippets and stored file resources redact secret-looking values before model-facing output.

File deletion and mutation are opt-in. filesystem_action tree is available by default, but write, move, and delete require TOKENHUB_ENABLE_FS_MUTATIONS=true on the TokenHub process; use it only in trusted local workspaces.

Git operations run in the workspace and can stage, commit, or branch when explicitly requested through git_action. Review paths and messages before allowing agent-driven git changes.

Network fetches, search providers, GitHub, npm, Sentry, Postgres, and browser capture can contact external services. Web and browser retrieval reject localhost, private LAN, metadata, and unverified DNS targets by default; set TOKENHUB_ALLOW_PRIVATE_NETWORK=true only for trusted local network debugging. Treat URLs, credentials, connection strings, and returned third-party content as sensitive. Do not place secrets in prompts when they can be passed as tool input, and prefer resource links over copying raw logs into chat.

read_resource can expand redacted resources; screenshots may still contain visible secrets from the captured page. Share resource URIs only with clients that should have access to the workspace resource store.

Troubleshooting

| Symptom | Fix | | --- | --- | | Missing search credentials | Use no-key DuckDuckGo fallback by omitting provider, or set BRAVE_SEARCH_API_KEY, EXA_API_KEY, TAVILY_API_KEY, or SERPAPI_API_KEY. | | GitHub, Sentry, or Postgres credential errors | Pass token for GitHub/Sentry or connectionString for Postgres in the MCP request. TokenHub does not read dedicated env vars for those providers today. | | Blocked network or provider timeout | Check outbound HTTPS access to the provider URL. Web fetch/search timeouts are currently fixed at 5000ms. | | Package install issues | Use Node 20 or newer, then retry npx tokenhub-mcp --root /path/to/workspace or npm install -g tokenhub-mcp. | | Windows path quoting | In MCP JSON, write paths as one escaped string such as "C:\\Users\\you\\workspace" and keep --root and the path as separate args. | | Unsupported workflow mode | Use execution: "answer_only" or execution: "plan_only" for resolve_request; direct implementation modes are intentionally rejected. | | Filesystem mutation blocked | Restart TokenHub with TOKENHUB_ENABLE_FS_MUTATIONS=true only for trusted local workspaces. |

Release Verification

Run the production release gate:

npm run verify:release

The script expands to:

npm run lint
npm test
npm run build
npm run eval:resolve-request
npm run eval:resolve-request:live
npm pack --dry-run
npm run smoke:install

Eval artifacts are written under artifacts/evals. The live eval uses live DuckDuckGo search and page fetches, so failures can reflect network or provider volatility.