Connect your client

Before connecting

Finish node and client-key setup and provider preparation. Have these ready:

• Your serving node’s HTTPS endpoint: https://YOUR-NODE/p/mcp-passthrough/mcp.
• A valid client token issued on that node, including its mcp_ prefix.
• An available model ID and a small agreed test budget.

Choose one client below. Replace YOUR-NODE and the example token; preserve the rest of the endpoint. Use the key issued by the node you connect to, not an upstream API token, seed phrase, or wallet password. Protect personal config files containing keys and never commit them.

These recipes use HTTPS. Connecting the client directly to an onion endpoint needs a separate Tor-capable connection; these examples do not configure one. The node’s Tor connection to network providers is a separate part of setup.

Cursor

Open your personal ~/.cursor/mcp.json on macOS/Linux, or %USERPROFILE%\.cursor\mcp.json on Windows. Merge this entry into mcpServers if the file already contains other servers:

{
  "mcpServers": {
    "eiou-passthrough": {
      "url": "https://YOUR-NODE/p/mcp-passthrough/mcp",
      "headers": {
        "Authorization": "Bearer mcp_REPLACE_WITH_YOUR_NODE_KEY"
      }
    }
  }
}

Save the file and enable the server in Cursor’s MCP settings. Reload Cursor if it does not appear. Confirm the eIOU tools are available, then follow the test sequence below. A project’s .cursor/mcp.json also works, but avoid putting a live token in a shared project. See Cursor’s MCP configuration guide.

Claude Desktop

Use a local stdio-to-HTTP bridge for this plugin’s static bearer authentication. Install a supported Node.js version with npm and npx, then open Settings → Developer → Edit Config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Merge this entry into mcpServers:

{
  "mcpServers": {
    "eiou-passthrough": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.14.3",
        "https://YOUR-NODE/p/mcp-passthrough/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${EIOU_AUTH_HEADER}"
      ],
      "env": {
        "EIOU_AUTH_HEADER": "Bearer mcp_REPLACE_WITH_YOUR_NODE_KEY"
      }
    }
  }
}

Leave ${EIOU_AUTH_HEADER} unchanged in args; put your actual token in the env value. This environment entry is still stored in the config file as plaintext. The bridge is third-party software and npx downloads the pinned version on first use. Fully quit and restart Desktop. If it cannot find npx, use its absolute installed path in command.

This uses Desktop’s local server configuration. Its remote Connectors flow runs from Anthropic’s cloud and has different reachability and authentication requirements; use the bridge recipe here for this plugin’s bearer key. See the local MCP setup guide, bridge documentation, and remote connector guidance.

Claude Code

Register the endpoint using HTTP transport. The example uses user scope, stored in ~/.claude.json, to make the server available across projects:

claude mcp add --transport http --scope user \
  eiou-passthrough \
  https://YOUR-NODE/p/mcp-passthrough/mcp \
  --header "Authorization: Bearer mcp_REPLACE_WITH_YOUR_NODE_KEY"
claude mcp get eiou-passthrough

Keep the real token out of saved shell history. In Claude Code, use /mcp to check the server’s status. See Claude Code’s MCP documentation for scopes and supported authentication configuration.

Test a model call

Use your client’s tool interface, or ask its assistant to call these tools explicitly. Approve only the small test call you intend:

1. Run chat.list_models and select an available model. Inspect its customer-facing price and currency.
2. Run balance.check and note the client key’s balance. If using agreed contact credit, the operator must also check that credit is available; this tool does not replace that check.
3. Run route.explain and route.status for the chosen model. They are free diagnostics, not a reservation or a guarantee that a later call will succeed. Ask the operator to inspect the route when testing a specific provider; customer diagnostics omit private routing details.
4. Call chat.completion once with a harmless prompt and a small output cap. The following is the tool’s arguments, not a standalone HTTP request:

{
  "model": "MODEL_ID_FROM_CHAT_LIST_MODELS",
  "messages": [
    { "role": "user", "content": "Reply with: eIOU pilot test complete." }
  ],
  "max_output_tokens": 32
}

5. Confirm the returned output and structuredContent billing fields: charged, currency, balance_after, and token counts. The short prompt is a connectivity test; do not rely on an exact phrase as proof of correctness.
6. Run usage.recent and balance.check again. On the node, check Usage for the matching key and call. For a network test, inspect the provider side and routing diagnostics too.

Only chat.completion is billed among these MCP tools. A call reserves balance for its allowed output before it runs, so a large output cap can fail even when the expected short response looks affordable. Provider warmup and provider-side API tests are separate operations that can spend funds.

Record the client/version, node/plugin versions, model ID, time, key ID, result and charged amount. Share error messages without tokens or private prompts. A local protocol fixture has checked the Cursor HTTP configuration and pinned Desktop bridge’s bearer handling; the pilot still needs to confirm behavior in each actual client application and against the chosen provider.

Troubleshooting

The endpoint returns 404: verify the plugin is enabled, its Public routes toggle is on, and the URL ends in /p/mcp-passthrough/mcp. Public routes must also be allowed by the host. A browser GET is not an MCP handshake; use the configured client to test the endpoint.

Authentication fails: check the complete mcp_... token, Bearer prefix, issuing node, expiry and revocation. In pilot mode, confirm the bound billing contact is still accepted. The node’s owner login is not a client key.

A discovered seller refuses access: check the serving node B is an accepted contact at the provider node C and the node clocks are correct. Pilot credential bootstrap uses a signed contact assertion. A catalog entry learned through another contact does not grant admission at the seller.

Models appear but no route is ready: inspect automatic routing, model enablement, currency, spending limits, peer state and settlement. Run eiou mcp-passthrough routing explain MODEL_ID and eiou mcp-passthrough peers list inside the node’s container. Warm providers after agreeing funding; allow pending payments to settle. Increasing a spending limit will not fix an admission error.

Insufficient balance: inspect both the client key’s balance/credit on the serving node B and that node’s provider prepayment at the provider C. Check top-up destination, memo, currency and settlement. Retry with a small output cap only after resolving funding.

No tools or connection timeout: confirm trusted HTTPS and reachability from the machine running the client or bridge. For Desktop, check npx is found and restart the application after editing config. Do not disable certificate verification to work around an untrusted endpoint.

A call fails after starting: inspect Usage and provider diagnostics before retrying. Large requests and slow providers can hit request-size or timeout limits. Failover may send the prompt to another provider; check the node’s policy and inference privacy.

For pilot help, contact the team with the diagnostic details above. Do not send live credentials.

Source: docs/CLIENTS.md at revision 07476eedee57.