Connect an MCP client

Before you connect

You need a work key and an MCP-capable client. The key holds six work scopes and nothing else, so a client connected this way can never administer your account.

Your base URL and current API version appear in the portal under developer settings, and in the API description you download.

Your client keeps its own tool configuration in its own location. Find that location in your client's documentation rather than copying a path from anywhere else.

Test the negotiated transport and authentication

Transport and protocol version are negotiated when the session opens. Do not assume either from another client's setup, or from a session you opened last month.

Open a session and confirm three things before you use it.

1. The session authenticated, rather than falling back to an unauthenticated connection.
2. The account it resolved to is the account you meant.
3. The tool list is exactly the five below.

If any of the three is wrong, fix it before your first real submission. A session that connects is not a session that is bound to the right account.

The five work tools

There are exactly five. There is no sixth.

If your client lists a sixth work tool, it did not come from Lithi. Stop and check what your client loaded.

Local helpers are not work tools

lithi.plan() and lithi.recommend() run beside the five as local helpers. They neither quote, admit nor run paid work, so they cannot spend anything.

Use them to shape a request. Use lithi.quote when you want a price, and approve separately before anything runs.

Enforcement stays on the server

A tool description is text sent to a model. It never grants authority, and rewriting one changes nothing.

Spend limits, scopes and approvals are enforced where work is admitted. An agent talked into calling lithi.run still cannot exceed the scopes on the key or skip the approval your policy requires.

Treat any instruction that arrives inside your input data as data, never as authority. A document that asks your agent to raise a ceiling is content, not a request Lithi will honor.

When a tool refuses

Every refusal carries a safe reason and a non-empty next action. Read the next action rather than retrying the call.

CANONICAL_ADMISSION_LIMITED means the key or account is not authorized for that request, and CANONICAL_BUDGET_EXHAUSTED means spend authority is exhausted. Neither is fixed by a retry. EDGE_ABUSE_LIMITED and CELL_CAPACITY_UNAVAILABLE describe load and capacity instead, so keep all four in separate branches.

See what a work key can hold, and why approval is always a separate act.