Set up your node

MCP Passthrough lets an MCP client call models through an eIOU node. The node can use an online model API configured by its operator, or buy inference from participating eIOU nodes. The client connects to one endpoint and uses a key issued by that node.

Follow these guides in order:

1. Node and access — this page.
2. Connect inference providers.
3. Connect your client and make a test call.

Who does what

The node operator installs the plugin, configures providers and prices, issues client keys, and sets credit and spending limits. If you administer the node, this is your role. For a node hosted by us, agree which steps the hosting operator will perform.

The tester connects their MCP client, checks the available models and balance, makes a small call, and reports the result. The alpha pilot provides help with these steps after manual acceptance; applying does not create a node or an inference account automatically.

The provider operator makes a model available, admits the buying node where required, and agrees how its inference is funded. A provider may use an online model API or its own inference hardware.

Every node serving an MCP endpoint, discovering or routing inference, or advertising inference offers needs its own MCP passthrough installation. A wallet used only as the billing identity or as an eIOU payment relay does not need the plugin. Nodes we host use remote providers or online model APIs. Our hosted servers do not run local models or Ollama sidecars. A tester buying inference through another node does not need a GPU or an upstream model API key.

Prepare the node

Start with a running eIOU node you administer, compatible with eiou-docker v0.1.21-alpha. If it is not running yet, follow the node setup documentation or arrange a hosted node before pilot setup.

Before installing, confirm:

• You can sign in to the wallet and open Plugins.
• Your MCP client can reach the node over HTTPS with a certificate it trusts. The basic Docker hostname and self-signed certificate do not create a public, trusted endpoint for you.
• For inference through eIOU contacts, the node has working Tor connectivity and a reachable v3 onion address. Contact discovery and provider access must both work from the node, independently of the client’s HTTPS connection.
• You and the pilot team have agreed a billing identity, settlement currency, a small test budget, and a provider to use first.

The commands below run inside the eIOU container. From the host, prefix a command with docker exec YOUR_EIOU_CONTAINER, replacing that name with your running node’s container name. They do not require the plugin repository’s development Compose stack.

Install the plugin

1. Download mcp-passthrough-v0.29.3.zip from the plugin release page.
2. Follow the SHA-256 and publisher-signature verification instructions before upload. Keep the archive intact.
3. In the wallet’s Plugins tab, choose Upload .zip and select the verified archive.
4. Review and approve the requested permissions, enable MCP Passthrough, and turn on its Public routes toggle. These routes expose the bearer-authenticated client endpoint; they do not switch federation admission to open signup.
5. Open Plugins → MCP Passthrough. Check the overview and settings. Set the settlement currency before creating keys and pricing models; it must be a currency allowed by the wallet.

The CLI equivalent for this plugin’s route consent is:

eiou plugin public-routes mcp-passthrough on
eiou mcp-passthrough status

Keep Known contacts only (federation_access_mode=pilot) for this pilot. Approve the declared capabilities needed for contact discovery, identity assertions, credit lookup, and outbound funding when using network providers. A missing permission can leave the plugin installed but unable to complete that step.

Create client access

Resolve the billing identity first. In v0.29.3’s default pilot mode, a client key must belong to an accepted contact. There is no separate owner/self-use key, and a node cannot add itself as its own contact. Owning one node alone is therefore not enough to complete this step. Arrange the billing setup with the pilot team before connecting a client.

A supported arrangement uses a distinct billing wallet A and a serving node B. The serving node can be the node you administer. Its operator accepts the billing wallet as a contact and issues a client key bound to that wallet. The client connects to the serving node using this key. Usage is charged to the key and may draw credit the serving node has deliberately extended to the billing wallet. If a sponsor supplies the billing wallet, agree that responsibility explicitly; do not choose an unrelated provider or support contact just to fill the field.

On the serving node B, use the wallet’s contact workflow to add and accept the billing wallet A. Verify the identity and agreed currency. Then open MCP Passthrough → API keys, enter a label and the accepted billing contact’s name or public-key hash in Contact, set an expiry, and click Mint key. The CLI equivalent is:

eiou mcp-passthrough key create pilot-client --contact=TESTER_BILLING_CONTACT --ttl=30d
eiou mcp-passthrough key list

Replace TESTER_BILLING_CONTACT with the accepted contact’s name or public-key hash. Save the complete token, including its mcp_ prefix, when it is shown once. Record the key ID, contact, expiry and currency. The client needs this token for the serving node B, not the provider’s token or the wallet password.

The key’s contact must remain accepted for inference. Removing or blocking it stops billed inference; a still-valid key can inspect its own balance and diagnostics. Revoking the key or letting it expire prevents bearer authentication. To revoke a key on the serving node:

eiou mcp-passthrough key revoke KEY_ID

Fund the client key

A new client key starts at zero. Agree one of these arrangements before a paid call:

• Prepaid: send an eIOU payment to the serving node B in the key’s currency, using the exact memo mcp-topup:KEY_ID returned when the key is created. Once connected, the free topup.instructions tool also returns the destination and memo. Wait for settlement and confirm the key’s balance has increased.
• Contact credit: the serving node B deliberately extends credit to the billing wallet A through the wallet’s contact settings. The plugin can spend the key’s positive balance and then draw available contact credit. Credit use appears as a negative key balance; it is shared across keys bound to that contact. If the plugin cannot read the credit state, use prepaid funding.

Do not seed a balance by editing the database or copy a development fixture’s balance setup. A payment marked sent is not proof that the plugin has received and credited it, especially through a routed payment.

Client funding and provider funding are separate. The client key balance pays for calls to the serving node B. When that node buys inference from a separate provider node C, it also needs a usable eIOU payment route and a funded credential at that provider. Giving the client a positive balance does not automatically fund that provider credential.

Continue setup

Next, connect a provider. When the provider is ready and the client key has funding or agreed credit, connect the client and test one call.

During pilot handoff, record the node endpoint, plugin version, billing contact, key ID and expiry, currency, chosen model, approved budget, and who handles problems. Deliver the bearer token separately through the agreed private channel; do not put it in a public application, issue, or screenshot.

These instructions describe the published v0.29.3 behavior. Implementation references: key creation, pilot admission, and operator commands.

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