MCP Client

packages/mcp-client translates local MCP calls into Tool Search API requests and manages the browser auth loopback flow.

This package is published as forza-tool-search and is designed to live in its own public repository via subtree sync from the private monorepo.

Install Into Your Editor

The recommended way to install Tool Search is the guided 3-step CLI:

npx forza-tool-search@latest init

This detects MCP hosts (Claude Desktop, Cursor, VS Code), asks for confirmation, writes the config, runs a demo search, and optionally signs you in for paid tools.

Current installer scope: macOS-first. Linux and Windows host autodetection are deferred.

CLI Flags

| Flag | Description | |------|-------------| | --yes | Auto-approve all prompts (non-interactive mode, skips auth) | | --skip-auth | Skip the sign-in step | | --verify-only | Check MCP config and server reachability, then exit (0/1) | | --pack <key> | Select a starter pack: prospect-research (default), lead-enrichment, outbound-prep | | --no-analytics | Disable anonymous install analytics | | --help, -h | Show usage and available starter packs |

Verify Installation

npx forza-tool-search@latest init --verify-only

Exits 0 if the config is present and the server is reachable, 1 otherwise.

Module Map

• src/cli.ts: CLI entrypoint, routes to init or MCP server
• src/init.ts: guided install flow, flag parsing, starter packs, verify-only mode
• src/server.ts: MCP surface wiring
• src/tools: search and outcome tool handlers
• src/auth: local session storage, paid-call auth guards, PKCE helpers, and the loopback callback server

Auth Config

• TOOL_SEARCH_SERVER_URL: Tool Search server base URL. Defaults to https://api.toolsearch.dev.
• MCP_CALLBACK_PORT: loopback port for the local callback listener. Defaults to 4318.
• TOOL_SEARCH_AUTH_TOKEN: optional Tool Search bearer token override for pre-authenticated environments.

Browser Auth Flow

1. The MCP client generates state, code_verifier, code_challenge, and a loopback callback_url.
2. The browser is opened to the web app connect page with those values.
3. The signed-in web app calls POST /api/auth/mcp/start using its Better Auth session.
4. The server returns a short-lived one-time auth code bound to the callback URL, state, and PKCE challenge.
5. The browser is redirected back to the local callback listener.
6. The callback listener validates state, exchanges { code, code_verifier } at POST /api/auth/mcp/exchange, and persists the returned Tool Search bearer locally.

Local Session Behavior

• The MCP client persists browser-issued Tool Search bearer state in ~/.config/tool-search/session.json.
• TOOL_SEARCH_AUTH_TOKEN overrides the file-backed session when present.
• Paid execution must use a Tool Search bearer. assertPaidExecutionEnabled() throws when neither the env var nor the local session exists.
• Paid execution also requires a Tool Search account with credits on the server. The MCP client cannot satisfy paid calls with browser auth alone or anonymous mode.
• The callback listener only accepts http://127.0.0.1/... and http://localhost/... redirect URLs in V1.
• The callback listener validates the browser state, exchanges the one-time auth code plus PKCE verifier, and stores the returned bearer and account metadata locally.
• POST /api/auth/mcp/exchange accepts only the one-time auth code plus PKCE verifier from the local MCP client.

Paid Call Requirements

• Search can run anonymously, but invoking a paid proxy URL requires the MCP client to send a Tool Search bearer issued by the browser auth flow.
• The MCP client must generate one Idempotency-Key per logical paid call and reuse that same key only when retrying the exact same request.
• Search responses now expose payment_protocol and paid_call_requirements.idempotency_key_required so clients can treat paid calls differently from free calls.
• The server pre-checks the tool's stored price estimate, available account credits, and spending caps before the upstream request is forwarded.
• If the upstream responds with 402, the MCP client does not pay directly. The server-side facilitator reserves credits, pays, retries once, and settles the actual amount server-side.
• Duplicate retries with the same Idempotency-Key replay the stored paid result instead of triggering a second upstream invocation.
• Paid proxy failures surface typed server errors such as authentication_required, insufficient_credits, and spending_cap_exceeded; the client should surface those errors without retry loops.

Registered Tools

search_tools

Input:

{
  "task": "Find lead-enrichment APIs for Salesforce campaign follow-up",
  "runtime": "node"
}

Behavior:

• Calls POST /api/search
• Sends x-tool-search-client: forza-tool-search so the server can attribute first-search onboarding analytics
• Forwards TOOL_SEARCH_AUTH_TOKEN as a bearer token when present
• Uses the server-provided contextual upgrade_hint.sign_in_url when paid tools are available
• Returns the server JSON payload directly to the agent

report_outcome

Input:

{
  "call_id": "00000000-0000-4000-8000-000000000000",
  "outcome": "success",
  "notes": "Call completed without retries"
}

Behavior:

• Calls POST /api/outcome
• Uses the existing call_id contract without reshaping it
• Returns { "status": "recorded" } on success

Running Locally

npm install
npm test
npm run build
TOOL_SEARCH_SERVER_URL=http://localhost:3001 npm run start

For local paid-call testing without going through the browser flow, you can still inject a pre-issued Tool Search bearer through TOOL_SEARCH_AUTH_TOKEN. That env var is only for Tool Search bearer tokens.

Startup logs go to stderr so stdio remains clean for MCP traffic.

Release

Before publishing, verify the package artifact directly:

npm run lint
npm test
npm run build
npm pack --dry-run

The public repo publishes tagged releases with npm provenance enabled.