Tutorial

Connect Token Saver to your AI host

Choose your harness for exact setup, OAuth, verification, and host instructions, then run the complete tier-first lifecycle.

Tip:Production lifecycle tools require OAuth. The consent screen links the host to your Elis account and the Personal or organization billing scope you choose.

Tip:The API can cold-start after a quiet period. If the first connection times out, open https://tryelisai.com/mcp, wait for it to report ready, and retry.

Choose your harness

Each tab is a complete setup path and has a shareable ?harness=... URL. Do not substitute one harness's endpoint or configuration keys for another.

Codex App ChatGPT Claude connector Claude Desktop Claude Code GitHub Copilot Gemini CLI Antigravity

Claude Desktop setup

Claude Desktop installs the packaged extension by drag-and-drop. The bundle ships its own MCP proxy, so no Node.js install or manual configuration is needed. The custom connector path (like Claude.ai) also works in Desktop.

1. Open the configuration

Settings → Extensions (the drop area reads "Drag .MCPB or .DXT files here to install")

2. Add Elis Token Saver

1. Download https://www.tryelisai.com/downloads/elis-token-saver.mcpb
2. Drag the file onto Settings → Extensions and confirm the install
3. Keep the default server URL unless you self-host Elis

3. Authorize

Enable the extension after installing. The first tool call opens the Elis sign-in and consent screen (OAuth 2.1).
Choose Personal or an organization on the consent screen. That choice controls billing and private-chain scope.

4. Verify the connection

Open Settings → Extensions and confirm Elis Token Saver is installed and enabled.
Start a new conversation, make sure the extension's tools are enabled for the chat, and request start_elis_token_saver_plan.

5. Install the host behavior

The extension supplies tools but does not install project files. Put the lifecycle rule in your Claude project instructions if you want it applied automatically.

Endpoint: https://api.tryelisai.com/api/mcp/claude

References: Download the extension (.mcpb) · Complete Elis setup reference

Run the complete Elis lifecycle

Connecting the server only exposes tools. The host must still use the same cursor for the whole plan and execute only the tasks Elis discloses. Every ready task includes an authoritative recommended_model_size of nano, small, or frontier. A named model is optional host guidance, not a hardcoded binding.

1. start_elis_token_saver_plan({ goal, constraints?, chain_hint? })
2. submit_elis_task_plan({ plan_id, tasks })       // only when start requests it
3. get_next_elis_task({ plan_id, graph_revision })
4. Execute every ready task using its public execution_handoff and size tier
5. get_next_elis_task({
     plan_id,
     graph_revision,
     previous_result: { task_id, status, output },
     usage: { input_tokens, output_tokens, model, model_tier }
   })
6. Repeat steps 4-5; switch immediately if the server returns a new graph_revision
7. finish_elis_plan({ plan_id, final_answer, total_tokens_used, usage, feedback })

Tip:The main session owns one stable plan cursor. A delegated executor receives the fullexecution_handoff, completes that one task, reports actual model and token usage, and returns control. It does not start a second plan.

Authorize a host without built-in OAuth

A raw JSON-RPC client must implement OAuth itself. First read public discovery metadata, register a public client, create an S256 PKCE challenge and state, open consent, validate the returned state, exchange the one-time code, and send the access token in the header.

Show the programmatic OAuth checklist

Read https://api.tryelisai.com/.well-known/oauth-authorization-server.
POST {"client_name":"my-host","redirect_uris":["http://localhost:8765/callback"]} to https://api.tryelisai.com/oauth/register and retain the returned public client_id.
Generate a random code_verifier, its base64url SHA-256 code_challenge without padding, and a random state.
Open /oauth/authorize with response_type=code, the exact redirect URI, code_challenge_method=S256, scope profile token_saver, the state, and the selected harness endpoint as resource.
Verify state, then POST the code, client id, verifier, exact redirect URI, resource, and grant_type=authorization_code to /oauth/token.
Call the selected MCP endpoint with Authorization: Bearer <access_token>. Keep tokens out of URLs and logs.

The copy-paste requests and refresh-token notes are in the full setup reference.

Use recall and privacy controls deliberately

A successful authenticated finish can store a proven chain privately in the selected Personal or organization scope. Future similar goals can recall that task sequence. Report honest ok, failed, or blocked task status and actual usage so prediction and savings audits compare against real execution.

// Do not store or recall this plan
start_elis_token_saver_plan({ goal, constraints: { no_store: true } })

// Keep private recall, but exclude this plan from community sharing
start_elis_token_saver_plan({ goal, constraints: { no_community: true } })

// Recall a known private proven chain for a similar goal
start_elis_token_saver_plan({ goal, chain_hint: "elis_chain:<sig>:<plan_id>" })

Troubleshoot the common failures

No tools: confirm the exact harness endpoint, Streamable HTTP config, host trust/enablement, and workspace MCP policy. Then refresh tools or restart the host.
oauth_required or invalid_token: the server is reachable, but the lifecycle is not authorized. Complete authentication again; do not continue anonymously.
insufficient_scope: authorize again with token_saver in scope.
payment_method_required: open https://app.tryelisai.com/billing, attach a payment method to the selected scope, then retry the lifecycle call.
First request times out: wake the API at https://tryelisai.com/mcp and retry after it reports ready.
/elis missing: apply every file returned by setup_elis_host_instructions and start a new host session. Gemini CLI can reload commands with /commands reload.
Plan revision changed: stop work tied to the old graph_revision and follow the new ready-task wave.

For tool schemas, usage fields, tier semantics, grounding, and finish behavior, continue to MCP Tools & Tier-First Lifecycle.