ToolHome

🌐 Language: English · 中文

ToolHome is a single-user, self-hosted control plane for MCP servers and Hosted CLIs. Manage upstream MCP capabilities, platform CLIs such as Azure az, GitHub gh, and Tailscale, and their encrypted credentials in one place.

It exposes two data planes:

• MCP: POST /mcp aggregates enabled servers; POST /mcp/{server_slug} preserves one server's original names and extensions.

• Hosted CLI: POST /cli/{slug}/exec runs an allow-listed argv array on the ToolHome host or in a pinned sibling container and streams NDJSON stdout/stderr/exit frames. GET /cli/{slug}/status runs the declared status probe.

ToolHome does not write harness-specific adapters for Claude Code, Codex, Cursor, or anything else. MCP clients use standard Streamable HTTP with Bearer auth; management and Hosted CLI operations use Control Keys.

For AI Agents

Install the ToolHome skill to teach your agent how to deploy and manage ToolHome:

npx skills add crayonlu/toolhome -g -y

This gives the agent knowledge of all CLI commands, OAuth flows, Market installation, troubleshooting, and deployment patterns. The agent will know when and how to use ToolHome without manual instructions.

Related MCP server: Mavryn

Web Console

The web console mirrors the full CLI surface: server and credential management, OAuth authorization, one-click Market installs, tool call observability, diagnostics, events, config export/import — with Chinese/English UI and mobile support.

Mobile:

Project Scope

ToolHome has two first-class planes:

• MCP: Remote-native servers use Streamable HTTP; Home-hosted servers use stdio on the ToolHome host; Node-hosted servers use stdio on a client machine, for capabilities that only exist there such as a local Chrome or a local Ghidra bridge. toolhome mcp launch <slug> runs one, and any MCP client reaches it with a single command line.

• Hosted CLI: platform CLIs represent an external service or control plane, for example Azure az, GitHub gh, and Tailscale. They are invoked with complete argv, stdin, timeout and output limits, allow/deny rules, and NDJSON output frames. Package managers and developer tools such as npm, go, cargo, uv, pipx, docker, and cursor are installer/runtime details, not Hosted CLI products.

Server placement is recorded in ToolHome rather than in each harness config, so a machine's local servers are defined once and reused by every client. A node-hosted server still runs with the user's own privileges on its machine, and it is unavailable while the ToolHome server is unreachable. The first release explicitly excludes multi-tenancy, profiles, workspaces, and project management.

Protocol Capabilities

The per-server entry proxies losslessly; the aggregate virtualizes conflicting names while keeping everything routable:

• Tools, Prompts, Resources, Resource Templates, Completion

• Resource subscriptions and list-changed notifications

• Sampling, Roots, Elicitation, and 2026 MRTR input_required

• Final Tasks extension: tasks/get, tasks/update, tasks/cancel, task-ID virtualization, and Mcp-Name binding

• MCP Apps: ui:// URIs are preserved on the aggregate; original App semantics on per-server entries

• Logging, Progress, cancellation, and custom extension methods

• Automatic 2026-07-28 / 2025-era negotiation, with remote SSE available as an explicit fallback

Downstream 2026 requests stay stateless; 2025-era clients use a persistent session bound to the authenticated principal, preserving initialize capability declarations and bidirectional request semantics. Parts of the Final Tasks extension not yet registered by SDK 2.0 are filled in by an isolated compatibility layer that still speaks the official tasks/* wire contract.

Aggregate capability lists serve an upstream from its last known good snapshot when its live list fails, so a transient upstream failure never changes the catalog between pages and client continuation cursors stay valid. Those upstreams are named in _meta["toolhome/stale-servers"]; a live list result always wins over the snapshot. An upstream that has never listed the surface and cannot list it now is reported in _meta["toolhome/failed-servers"], and when no upstream can supply any list data the list returns a protocol error. Cancelling a client request preserves upstream runtime status. Individual endpoints report their own upstream errors.

Aggregated tool names use {server_slug}_{encoded_upstream_name}. UTF-8 bytes outside ASCII letters and digits are encoded as -hh (hex), so github.search_code becomes github_search-5fcode. Long names are shortened with a stable hash. Prompts retain {server_slug}.{upstream_name}. Unknown extension methods use toolhome/{server_slug}/{upstream_method} on the aggregate and pass through untouched on per-server entries. MCP Apps that use original tool names are routed by App resource context or globally unique names; use a per-server entry when names collide.

When a modern harness calls a legacy upstream, ToolHome suspends push-style Elicitation, Sampling, and Roots in Tool, Prompt, and Resource Read calls, converts them to modern input_required multi-turn interactions, then resumes the same upstream request. Legacy extensions that issue private server-to-client requests inside a custom method have no standard representation in the closed MRTR type set; use a legacy harness or upgrade the upstream protocol for those.

See architecture and protocol compatibility for details.

Quick Start

Requires Node.js 24 or newer.

npm install
cp .env.example .env

Generate two independent random values for TOOLHOME_MASTER_KEY and the first-boot TOOLHOME_BOOTSTRAP_CONTROL_KEY. Both must be at least 32 characters and must differ.

npm run build
set -a
source .env
set +a
npm start

Open TOOLHOME_PUBLIC_URL and sign in to the web console with the bootstrap Control API Key. Once you create a new Control Key, you can revoke the bootstrap key.

For development, run the server and web separately:

npm run dev
npm run dev:web

Vite proxies /api requests to http://127.0.0.1:3344.

Docker

export TOOLHOME_MASTER_KEY="$(openssl rand -base64 48)"
export TOOLHOME_BOOTSTRAP_CONTROL_KEY="tch_ctl_$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')"
export TOOLHOME_PUBLIC_URL="https://tool.cyncyn.xyz"
export TOOLHOME_ALLOWED_HOSTS="tool.cyncyn.xyz"
docker compose up -d --build

Put an HTTPS reverse proxy in front of ToolHome in production. OAuth callbacks, URL-based Client IDs, and remote harness connections should all use a stable HTTPS TOOLHOME_PUBLIC_URL. The value must be a canonical origin — no path, query, fragment, username, or password. Data lives in /data/toolhome.sqlite (SQLite, WAL mode).

Market installers are hidden behind curated capability entries. The catalog can use npm, Go, GitHub Release archives, uvx, or Docker recipes; the product surface remains MCP servers and Hosted platform CLIs. Uvx entries execute the installed binary from the persistent ToolHome tool directory instead of resolving the package again on every refresh. Docker-backed entries require the Docker socket mount shown in docker-compose.yml. Hosted CLI state directories are explicit named volumes, never implicit mounts of a user's local credential directory.

CI/CD

GitHub Actions (.github/workflows/ci.yml) runs on every push to main or tag:

1. test: server check + test, web typecheck + test

2. docker: build dists -> docker build -> push ghcr.io/crayonlu/toolhome:latest (tags also get :v*)

3. deploy: SSH to server docker compose pull && up -d

Deployment requires three GitHub Secrets: DEPLOY_HOST, DEPLOY_USER, DEPLOY_KEY (SSH private key). The GHCR package must be set to Public (after first push, in Package Settings).

Market

The Market ships curated MCP servers and Hosted platform CLIs. Installing an entry creates the encrypted Credential and the corresponding Server or CLI record:

npm run cli -- market list
npm run cli -- market install resend --set RESEND_API_KEY=re_xxx
npm run cli -- market install gh-cli --set GH_TOKEN=ghp_xxx
npm run cli -- market uninstall gh-cli

• MCP entries may be remote, npm-backed, uvx-backed, or Docker-backed.

• Hosted CLI entries include Azure az, GitHub gh, and Tailscale. They pin the platform artifact, define allowed argv, and declare how stored credential material reaches the CLI.

• A CLI can use a bearer token (GH_TOKEN), selected Env Credential variables (Azure service principal), or an OAuth access token after the shared MCP authorization flow completes.

• The web console's Market page offers the same flow graphically. MCP/CLI is a plane switch: only entries and records from the selected plane are shown.

Connecting a Harness

First create an MCP Access API Key from the console or CLI. The generic aggregate configuration is:

{
  "url": "https://tool.cyncyn.xyz/mcp",
  "headers": {
    "Authorization": "Bearer tch_mcp_..."
  }
}

For a single GitHub server only:

{
  "url": "https://tool.cyncyn.xyz/mcp/github",
  "headers": {
    "Authorization": "Bearer tch_mcp_..."
  }
}

Access Keys only call the MCP data plane; they cannot read server or credential configuration. Control Keys only call the control plane and cannot be used as an MCP identity.

The data plane also implements OAuth 2.1: a harness can discover the authorization server via RFC 9728 metadata and use Authorization Code + PKCE to obtain an access token bound to a specific MCP endpoint.

Downstream Dynamic Client Registration returns a stateless Client ID signed with the master key — no in-process registry, valid across restarts with the same key. HTTPS URL-based Client Metadata is also supported, with limits on response size, redirects, and non-public targets.

Tool Exposure Modes

The aggregate POST /mcp endpoint supports two exposure modes. full is the default and lists every enabled server's tools directly. compact is opt-in and exposes exactly two tools:

• search — action: "servers" lists the usable server catalog, action: "find" ranks tools for a task, and action: "describe" returns a selected tool's complete input schema.

• exec — runs one exact tool returned by search, validating that tool's current contract before a fresh call.

Enable it per entry, not globally:

• Host: TOOLHOME_MCP_TOOL_MODE=compact.

• Local node: toolhome mcp stdio --tool-mode compact.

Discovery reads only definitions already stored on the entry: search makes no upstream request and spawns no process. Execution connects only to the selected server. After changing the mode, reconnect the client because many clients cache tools/list. Individual /mcp/{server_slug} endpoints and full behavior are unchanged.

Response budgets and compatibility. Complete MCP directory and candidate-summary results are limited to 8 KiB; complete definitions are limited to 16 KiB. Definitions include the argument contract and required upstream instructions. Oversized definitions return definition_too_large with full/individual-endpoint guidance; execution enforces the same limit. Business results preserve upstream content. Servers with MCP Apps use individual endpoints; Task-required tools and incompatible Task requests receive guidance before side effects. After definition_changed, describe the tool and explicitly invoke exec again. may_have_run means an earlier invocation may have produced effects, so check its state first. Modern upstreams own their suspended state; the current protocol has no generic suspended-invocation termination method.

Retrieval scope. The first version uses local lexical ranking. Chinese-only tasks commonly need English tool or task keywords; native Chinese semantic retrieval remains a limitation. Fixed definitions reduce initial tool schemas. Complete task cost includes discovery rounds, complete contracts and business outputs, and should be measured for the actual client.

Discovery latency. Aggregate continuation pages reuse the successful live list from the first page for up to 30 seconds, scoped to the caller, client capabilities and request parameters. New traversals still read upstream lists; catalog/projection changes invalidate reuse, and partial failures are retried. The local stdio entry serves ordinary discovery from the owning node's persisted capability mirror without spawning children. Run toolhome node status --check to refresh that mirror after changing a local tool installation; tool calls still connect and validate the live upstream contract. Clients advertising additional capabilities retain live discovery.

Stable definitions. Aggregate tools/list emits canonical object key order while preserving array order, so a catalog that only reorders equivalent upstream schema objects serializes to identical bytes. A client that places tool definitions at the front of a model request keeps a reusable prefix across such refreshes; a real definition change still changes the bytes. The per-server endpoint keeps upstream key order unchanged.

Local scope. Node-placed servers still run only on their owning machine, and the local compact catalog covers only servers placed on that node. At startup the local entry mirrors the control plane's tool visibility; if a server's projection cannot be read it stays out of the compact catalog (fail closed) until the next start or explicit refresh. Changing visibility on the control plane requires the local entry to reconnect before it takes effect.

Node label. toolhome mcp stdio binds its local mirror to the node label from --node or nodeId in the CLI config, falling back to the hostname. Keep that label stable: auth login preserves it, and a mirror opened under a different label reports the label it belongs to instead of failing with a bare key error.

Roll back to full. Set TOOLHOME_MCP_TOOL_MODE=full (or remove it) on the host, or drop --tool-mode from toolhome mcp stdio, then reconnect the client. No data migration is needed: full mode clears any compact-mirrored visibility rows so every enabled tool is exposed again.

Keep one discovery layer. Do not nest ToolHome compact behind an upstream that already performs its own search/exec or Code Mode. Pick either ToolHome full/individual endpoints or the upstream's full tool list. For Cloudflare API MCP, opt out explicitly yourself with its documented ?codemode=false URL; ToolHome never rewrites upstream URLs or query parameters, and truncateToolResult is a separate switch that is never changed for you.

Upstream Authentication

Remote-native servers support:

• Bearer token

• API key header

• Multiple custom headers

• OAuth 2.1 / OIDC

OAuth/OIDC uses the official MCP TypeScript SDK auth orchestrator, covering RFC 9728 discovery, Authorization Server/OIDC metadata, PKCE, RFC 9207 issuer validation, CIMD, DCR, refresh, and RFC 8707 resource indicators. An OAuth Credential is bound 1:1 to a Remote Server, preventing token reuse across resources or issuers.

If an upstream authorization server advertises URL-based Client Metadata support but cannot fetch it from a proxied origin (for example Cloudflare-hosted MCP), set TOOLHOME_OAUTH_URL_CLIENT_ID=false to force Dynamic Client Registration.

Home-hosted servers use an Environment Credential or the transport's own env.

Put secrets in Credentials, not in Remote URL query strings or stdio arguments — the latter are structural configuration and cannot be reliably redacted.

CLI

After building, run toolhome; from source, use npm run cli --.

export TOOLHOME_URL="https://tool.cyncyn.xyz"
export TOOLHOME_CONTROL_KEY="tch_ctl_<your-control-key>"
# Optional: override the default ~/.config/toolhome/config.json path
export TOOLHOME_CONFIG="$HOME/.config/toolhome/config.json"
npm run cli -- auth login

npm run cli -- server list
npm run cli -- server add ./server.json
npm run cli -- cli list
npm run cli -- cli status az
npm run cli -- cli exec az -- account show
npm run cli -- cli exec gh --stdin-file ./input.txt -- issue list
npm run cli -- credential authorize cloudflare
npm run cli -- access-key create laptop
npm run cli -- endpoint aggregate
npm run cli -- doctor

cli exec sends an argv array to the hosted CLI and streams stdout/stderr without invoking a shell. Put -- before CLI arguments that start with -; --stdin and --stdin-file feed remote stdin, and --output json emits one JSON object per frame plus the final exit outcome:

npm run cli -- cli exec az --timeout 30000 -- account show --subscription "$SUBSCRIPTION_ID"
npm run cli -- cli exec gh --stdin-file ./issue.md -- issue create --title "Bug" --body-file -
npm run cli --output json -- cli exec host-shell -- -c 'printf hello'

The CLI command family also supports cli get, cli add, cli update, cli delete, cli enable, and cli disable. cli exec returns exit status 0 only when the hosted process reports result: "ok"; SIGINT/SIGTERM abort the HTTP stream and the remote process.

credential authorize <name> resolves by credential name (or id), opens the browser, and waits until authorization succeeds, fails, or times out:

npm run cli -- credential authorize notion --server notion   # explicit server (auto-resolved if omitted)
npm run cli -- credential authorize notion --force            # clear the old client and re-authorize
npm run cli -- credential authorize notion --no-open          # don't open the browser
npm run cli -- credential authorize notion --no-wait          # print the URL and exit
npm run cli -- credential authorize notion --timeout 300      # wait time in seconds (default 600)

The CLI exposes a command for every Control API capability plus a general escape hatch:

npm run cli -- api GET /api/v1/openapi.json

Config export is redacted and reviewable by default, and cannot be used to restore. Credential payloads, static HTTP header values, and stdio transport env values are hidden. When secrets are explicitly included, the CLI writes the file with 0600 permissions; import rebuilds credentials, remaps related IDs, and rolls back atomically in a single SQLite transaction if any step fails.

npm run cli -- config export backup.json --include-secrets
npm run cli -- config import backup.json

Backups contain plaintext secrets and deserve the same protection as the master key. --include-secrets requires an explicit output file to avoid leaking secrets into terminal logs, and the CLI forces 0600 after writing. Omit it for routine review.

Configuration

Security Model

• Upstream secrets are AES-256-GCM encrypted before being written to SQLite.

• The database stores an encrypted master-key check; booting with the wrong master key fails immediately instead of silently locking existing API keys.

• API Keys are stored only as HMAC digests; the full secret is returned once at creation.

• Control and MCP Access Keys use distinct prefixes and validation domains.

• The web console exchanges the Control Key for a short-lived, HttpOnly, SameSite=Strict session cookie.

• Downstream OAuth tokens have exact endpoint audiences; an aggregate token cannot call per-server endpoints and vice versa.

• OAuth callbacks validate state, PKCE, issuer, and discovery state.

• URL-based client metadata rejects private-network and insecure targets and pins validated public-resolved addresses for HTTPS fetches, reducing SSRF and DNS-rebinding risk.

• Downstream DCR Client IDs are signed with the master key, verifiable across restarts, and never stored in the database.

• Diagnostic events keep the last ~10,000 entries; Home-hosted stderr is redacted against transport env and Environment Credential values before entering the event stream.

Back up the database and TOOLHOME_MASTER_KEY, or keep a tightly protected --include-secrets config export. Losing the master key makes encrypted credentials in the original database unrecoverable.

Engineering Commands

npm run check
npm run format:check
npm run build
npm run test
npm run test:real

npm run test:real prefers to launch the built ToolHome process and connects Home-hosted stdio and Remote-native HTTP fixtures. It uses the official MCP Client to verify aggregate/per-server entries, modern/legacy harnesses, Progress, cancellation, list-changed, MRTR, Tasks, and auth boundaries; it falls back to source entry points when no build artifact exists, which is handy for local debugging.

/healthz reports process liveness only; /readyz returns 503 while runtime state is unavailable.

License

MIT