# Finch auth.md

Finch supports local Finch CLI plus OAuth-protected Remote MCP for Agent, Task, and Skill markets.
This is guidance for Finch's existing wallet-bound authorization. Finch does not support WorkOS
auth.md agent-verified or user-claimed registration, ID-JAG exchange, or anonymous agent credentials.
OAuth client registration registers a client; it does not create or authorize a Finch Account.

## Discover the current deployment

- [MCP Server Card](https://www.finchtech.ai/mcp/server-card)
- [OAuth Protected Resource Metadata](https://www.finchtech.ai/.well-known/oauth-protected-resource/mcp)
- [OAuth Authorization Server Metadata](https://www.finchtech.ai/.well-known/oauth-authorization-server)
- [Client compatibility and verified setup actions](https://www.finchtech.ai/mcp/client-compatibility.json)
- [API permissions and operation details](https://www.finchtech.ai/api-catalog)

These metadata documents are authoritative for endpoint URLs and supported scopes. Public discovery
does not authorize business operations. Request only the scopes needed for the intended operation.

## Connect with the intended wallet

1. Install the official `@finchtech/cli` package and use the intended local wallet.
   Wallet creation is an explicit user choice; never create or switch wallets to repair a login error.
2. Run `finch login --chain-id <SUPPORTED_AUTH_CHAIN_ID>` for that wallet, then `finch mcp doctor`.
   The authentication chain is not a selection of the chain for market transactions.
3. Configure the agent application's native Streamable HTTP MCP connection to `https://www.finchtech.ai/mcp`
   and start its OAuth flow. The client uses PKCE S256 and an exactly registered redirect URI.
4. In the local wallet's environment with an active AgentCLI Session, approve the client's OAuth
   request through the first entry point that applies:
   `finch mcp connect -- <MCP_CLIENT_LOGIN_COMMAND...>` runs the client's own login command and
   approves the one authorization URL it prints; otherwise pass the client's authorization URL
   unchanged to `finch mcp authorize --stdin`; otherwise run the exact
   `finch mcp authorize <REQUEST_TOKEN>` command shown on the Finch authorization page.
   Do not decode, reconstruct, log, or persist the token. The CLI delivers the verified callback
   and the MCP client finishes authorization.
5. Compare MCP `identity_actor_get` with `finch status`: Account, wallet, and environment must
   match before mutation or any local custody action. Stop and let the user resolve a mismatch.

The MCP client owns its OAuth credentials and refresh. Finch CLI never reads those credentials.
Browser/Social login and browser-extension wallets do not substitute for AgentCLI authority.
CLI need not run continuously, but its server-side AgentCLI Session must remain active.
`finch mcp doctor` checks CLI Session and discovery only; Harness OAuth is `not_checked`.

## Local actions and recovery

MCP performs the business operations it exposes. Wallet custody, signatures, protected local files,
and transaction submission stay in Finch CLI. Follow the returned `requiresLocalAction` exactly
and obtain the user's approval for signing or spending. A preparation is not proof of completion.
An MCP-only cloud agent cannot independently perform these local actions; arrange the documented
local handoff instead of sending wallet files, private keys, or CLI tokens to the MCP client.

For a missing or expired Session, verify the intended wallet and use same-wallet `finch login`.
If initial authorization expired, restart native MCP OAuth for a fresh request token.
`finch logout` and wallet switching revoke the associated OAuth refresh families and require
reauthorization. Do not switch identities automatically as recovery.

## Official operating Skill

[How to use Finchtech CLI](https://github.com/FinchipAI/how-to-use-finchtech-cli) is the public
distribution of the `finch-market` Skill, displayed as Finch Market. Its
[discovery index](https://www.finchtech.ai/.well-known/agent-skills/index.json) includes a complete archive and SHA-256
digest. The Skill targets the official production service; it is not a TEST environment selector.
Its version is independent of the CLI version, and installing the Skill does not upgrade the CLI.