@solotech/mcp

Local MCP client for Solo Router — a chameleonic discovery layer for the AI agent economy.

This package runs on your machine as an MCP server (over stdio). It exposes a single tool, discover_tools. When you describe your intent, it queries the Solo Router search engine, gets a curated list of third-party MCPs, and surfaces their tools to your agent as if they were native. tools/call is proxied locally to the third-party MCP — credentials never leave your machine.

Install

npm install -g @solotech/mcp

Configure your agent

Claude Desktop / Claude Code

Add to your MCP servers config:

{
  "mcpServers": {
    "solo-router": {
      "command": "solo-mcp"
    }
  }
}

Cursor / other MCP-aware tools

Use the binary solo-mcp (stdio transport).

Authentication

Some MCPs require credentials (Bearer tokens, API keys). @solotech/mcp reads them from a local file:

~/.solo-router/secrets.env

Format (one entry per MCP):

# By name (uppercased, non-alphanumeric → underscore)
POLYMARKET=Bearer eyJhbGciOiJIUzI1NiI...
HUGGING_FACE_HUB=hf_xxxxx

# Or by mcp_id (canonical, takes precedence)
aa25f247-2bf3-40ef-8a87-a3a35d6ada57=Bearer xxx

When you call discover_tools and a matched MCP requires a credential you don't have, the response tells you the URL where to obtain a token plus instructions provided by the MCP author. Add the line, save the file, then call discover_tools again — secrets are re-read on every discover.

The header name for injection is provided by the MCP (default Authorization). The value you put in secrets.env is the full header value, e.g. Bearer xxx or xxx, depending on what the upstream MCP expects.

Environment variables

| Var | Default | Purpose | |---|---|---| | SOLO_WORKER_URL | https://solo-router.nightwalkax.workers.dev | Search-engine endpoint | | SOLO_CONFIG_DIR | ~/.solo-router | Where to read/write secrets and client id | | SOLO_TELEMETRY | off | Set to on to send anonymous telemetry. See "Privacy" below | | SOLO_DISCOVERY_TOP_N | 8 | Max number of MCPs returned per discover call | | SOLO_UPSTREAM_TIMEOUT_MS | 15000 | Per-call timeout against third-party MCPs |

Privacy

By default, nothing leaves your machine except the discovery query (the intent text you describe to the agent). The discovery query is sent over HTTPS to the Solo Router search engine.

Setting SOLO_TELEMETRY=on enables opt-in telemetry. When enabled, the client posts:

| Field | Example | Purpose | |---|---|---| | client_id | 8e2c1d9f-... (random uuid persisted in ~/.solo-router/client-id) | Group queries from one install. Not linked to your user account, IP, OS, or hardware. | | intent | the same string you typed for discover_tools | Improves ranking and surface unmet demand to MCP providers | | mcp_id | uuid of the matched MCP, or null | Which MCP was assigned for this query | | success_status | success | error | validation_failed | Whether the call worked, failed validation, or upstream errored |

What is not sent:

• Tool arguments (the actual data you pass to the upstream MCP)
• Tool results (what the upstream returned)
• Auth tokens or any contents of secrets.env
• Your IP (logged only by Cloudflare for rate limiting; not stored alongside intent rows)
• Username, hostname, or anything that identifies you personally

You can revoke at any time by removing SOLO_TELEMETRY=on. To delete past data, contact the operator (telemetry rows are keyed by client_id).

Stop and reset

• Stop the server: kill the process. Your agent host (Claude Desktop, etc.) restarts it on demand.
• Forget all secrets: rm ~/.solo-router/secrets.env.
• New anonymous identity: rm ~/.solo-router/client-id (a new uuid is generated next start).

How it works

┌──────────┐  stdio  ┌──────────┐  HTTPS  ┌────────────────┐
│  Agent   │ ◀─────▶ │ solo-mcp │ ◀─────▶ │ search engine  │
│ (Claude) │         │ (local)  │         │ (Cloudflare)   │
└──────────┘         └────┬─────┘         └────────────────┘
                          │  HTTPS (with your local creds)
                          ▼
                   ┌──────────────┐
                   │  Third-party │
                   │  MCP server  │
                   └──────────────┘

The search engine ranks MCPs against your intent (semantic similarity + tier + trust score) and returns metadata, including each MCP's declared tools_schema. The local client:

1. Maintains the two-step manifest contract: only discover_tools is exposed initially.
2. After a discovery match, registers the matched tools as native (qualified <mcp_id>::<tool_name>).
3. Emits notifications/tools/list_changed so your agent refreshes.
4. Validates tools/call arguments against the MCP's inputSchema locally before dispatching.
5. Injects your local credential into the upstream call (header name from the MCP, value from secrets.env).
6. Returns the upstream result back through the agent.

License

See LICENSE.