developers/cli-and-mcp.md

Finch CLI and Remote MCP

Connect an Agent client while keeping wallet signing, credentials, and protected files local.

Remote MCP handles market discovery, account-scoped business operations and preparation. Finch CLI keeps wallet signing, Session state, protected files, packaging and chain submission on your machine. Keep private keys and OAuth credentials within their owning applications.

Install CLI 0.3.1

Use Node.js 20 or newer and the official @finchtech/cli package. This guide requires CLI 0.3.1 or newer for current Skill search and publication requests.

bash

pnpm add -g @finchtech/cli@0.3.1
finch --version

The primary command is finch; finchtech is an equivalent alias. The former finchip-cli package is deprecated. Installing a Skill does not upgrade the CLI executable.

Add the Finch Market Skill

Use the official Finch Market Skill repository and its tagged releases. Add SKILL.md, references/ and agents/ together through your Agent client’s supported Skill installation mechanism. Read the README for the required CLI version. The Skill supplies operating instructions; it does not configure MCP, log in, or grant wallet authority.

Establish the local Finch identity

Use the intended existing wallet. Creating a new wallet is a separate decision because it represents a distinct Finch Account when used.

bash

finch wallet show
finch login
finch status

Never paste private keys, seed phrases, bearer tokens, content keys or protected credentials into an Agent conversation or browser form.

Connect Codex to Remote MCP

Configure the official remote endpoint using the Agent client’s native MCP and OAuth flow:

bash

codex mcp add finch --url https://www.finchtech.ai/mcp
codex mcp login finch

When the authorization page displays a one-use command, run it unchanged with the intended wallet and active local AgentCLI Session. The argument is a request token, not a URL:

bash

finch mcp authorize <REQUEST_TOKEN>

Do not decode, reconstruct, log or persist the token. If the Session is missing, log in with the intended wallet and restart OAuth for a fresh request. Let the Agent client finish its callback and retain its own OAuth credentials.

bash

finch mcp doctor

Browser login is separate

bash

finch site open

This opens Finch using the local AgentCLI Session. If an ordinary Finch page supplies a Browser login request URL, verify the official Finch origin and use that exact URL:

bash

finch site login "<REQUEST_URL>"

Use these commands on the machine with the CLI, wallet and graphical browser. A Browser Session does not receive private keys or permission to complete local signing actions.

Check identity and use prepared actions

Before mutation and each local custody action, call Remote MCP identity_actor_get and run finch status. Account ID, wallet and environment must match exactly. On mismatch, stop and choose the intended identity; never silently create or switch wallets.

Follow the returned operation ID, signing summary and exact local command. Obtain approval for the concrete signing or transaction action. Do not reconstruct calldata, prices, hashes or provider requests.

Skill search, publication and download

Search continuation: pass the returned nextCursor unchanged to finch skill search --cursor. Keep the same filters; restart from page one if the cursor is stale. CLI 0.3.1 advertises the current search capability automatically.
A single ZIP uses a file source plan. The CLI validates and packages it locally; include SKILL.md, README.md or an unambiguous root Markdown document. New Skills use SkillRoot; historical Skills retain compatible updates.
Finch-managed publication key requests are timestamped and one-use. If a signature expires or was consumed, use the updated client to sign a fresh request; do not replay the old signature.
Encrypted downloads use device-sealed Oracle V2 delivery, including historical encrypted packages. Run the returned finch skill download action so verification and decryption stay local.

Recover an interrupted operation

Read the operation or durable local journal after an uncertain response.
Preserve the same operation ID and idempotency key.
Use the exact typed recovery command reported by the CLI. Never rebroadcast a recorded transaction or regenerate recorded award signatures.
Keep recovery records until terminal success; report the last confirmed stage.

Official links

developers/cli-and-mcp.md

Finch CLI and Remote MCP

Connect an Agent client while keeping wallet signing, credentials, and protected files local.

Install CLI 0.3.1

Use Node.js 20 or newer and the official @finchtech/cli package. This guide requires CLI 0.3.1 or newer for current Skill search and publication requests.

bash

pnpm add -g @finchtech/cli@0.3.1
finch --version

The primary command is finch; finchtech is an equivalent alias. The former finchip-cli package is deprecated. Installing a Skill does not upgrade the CLI executable.

Add the Finch Market Skill

Establish the local Finch identity

Use the intended existing wallet. Creating a new wallet is a separate decision because it represents a distinct Finch Account when used.

bash

finch wallet show
finch login
finch status

Never paste private keys, seed phrases, bearer tokens, content keys or protected credentials into an Agent conversation or browser form.

Connect Codex to Remote MCP

Configure the official remote endpoint using the Agent client’s native MCP and OAuth flow:

bash

codex mcp add finch --url https://www.finchtech.ai/mcp
codex mcp login finch

When the authorization page displays a one-use command, run it unchanged with the intended wallet and active local AgentCLI Session. The argument is a request token, not a URL:

bash

finch mcp authorize <REQUEST_TOKEN>

bash

finch mcp doctor

Browser login is separate

bash

finch site open

This opens Finch using the local AgentCLI Session. If an ordinary Finch page supplies a Browser login request URL, verify the official Finch origin and use that exact URL:

bash

finch site login "<REQUEST_URL>"

Use these commands on the machine with the CLI, wallet and graphical browser. A Browser Session does not receive private keys or permission to complete local signing actions.

Check identity and use prepared actions

Skill search, publication and download

Search continuation: pass the returned nextCursor unchanged to finch skill search --cursor. Keep the same filters; restart from page one if the cursor is stale. CLI 0.3.1 advertises the current search capability automatically.
A single ZIP uses a file source plan. The CLI validates and packages it locally; include SKILL.md, README.md or an unambiguous root Markdown document. New Skills use SkillRoot; historical Skills retain compatible updates.
Finch-managed publication key requests are timestamped and one-use. If a signature expires or was consumed, use the updated client to sign a fresh request; do not replay the old signature.
Encrypted downloads use device-sealed Oracle V2 delivery, including historical encrypted packages. Run the returned finch skill download action so verification and decryption stay local.

Recover an interrupted operation

Read the operation or durable local journal after an uncertain response.
Preserve the same operation ID and idempotency key.
Use the exact typed recovery command reported by the CLI. Never rebroadcast a recorded transaction or regenerate recorded award signatures.
Keep recovery records until terminal success; report the last confirmed stage.