# Finance OS — connecting an AI agent

Finance OS is a tax-first bookkeeping and filing system. An AI agent connects to a person's
Finance OS account through the Model Context Protocol (MCP) and is authorized by that person
exactly once, in their browser. With the standard sign-in below, no API key or token is ever
typed, copied, or shared.

## The one thing an agent needs

    https://www.finance.fyi/api/mcp

Connect to that address with Streamable HTTP MCP. Everything else is discoverable.

## How the connection authorizes itself (standard MCP authorization)

1. An unauthenticated request to /api/mcp returns 401 with a WWW-Authenticate header whose
   resource_metadata points at
   https://www.finance.fyi/.well-known/oauth-protected-resource/api/mcp
2. That document names the authorization server (https://www.finance.fyi) and the scopes.
3. https://www.finance.fyi/.well-known/oauth-authorization-server lists the endpoints:
   registration, authorization, token, revocation. PKCE S256 is required. Dynamic client
   registration (RFC 7591) and client-ID metadata documents are both accepted.
4. Register a public client, then open the authorization URL for the account owner. Native
   clients use a loopback redirect (http://127.0.0.1:<port>/…, RFC 8252); the port may be
   ephemeral.
5. The owner signs in (two-factor required) and sees one consent screen naming the client and
   its exact permissions. On approval the browser is redirected straight back to the client's
   redirect URI with the authorization code.
6. Exchange the code at the token endpoint with the PKCE verifier. Access tokens are short-lived
   and bound to the /api/mcp resource; refresh tokens rotate.

MCP clients that implement the MCP authorization specification (Claude Code, Codex, and others)
do all of this automatically when given the address. An agent working from a shell can do it
with curl and a loopback listener.

## From a shell: the command-line tool and its skill

An agent that works from a shell, with no MCP client of its own, can use the Finance OS
command-line tool. It signs in with the same browser approval and then runs any tool.

    npm install -g finance-os
    finance-os login
    npx skills add https://www.finance.fyi

On a machine with no browser, run `finance-os login --start`, give the account owner the sign-in
link it prints, and finish with `finance-os login --finish "<the address their browser ended on>"`.
The same package is served at https://www.finance.fyi/cli/finance-os.tgz, which `npm install -g`
also accepts. Then `finance-os next` lists what to do, `finance-os playbook` explains how, and
`finance-os call <tool> '<json>'` runs a tool. The skill is also at
https://www.finance.fyi/skills/finance-os/SKILL.md and is indexed at
https://www.finance.fyi/.well-known/agent-skills/index.json.

Never ask the owner to paste an API key or a password into a chat.

## Scopes

Owner approval for the standard MCP connect path always grants the complete agent bundle:

mcp finance:read finance:write tax:read tax:prepare documents:read documents:write
packages:read packages:generate approvals:decide

Clients may request a subset during discovery, but Finance OS never issues a partial OAuth token
for `/api/mcp`. Existing OAuth tokens with fewer scopes are upgraded to the full bundle at token
exchange, refresh rotation, and MCP verification.

approvals:decide lets the agent relay an approval the owner gives inside the conversation for an
exact, digest-bound request. It never lets the agent consent, sign, submit, pay, or delete on
its own.

## What a connected agent can and cannot do

Can: read the owner's complete books, evidence, filings, forms, and work items; prepare
bookkeeping entries, tax positions, form drafts, and filing packages; queue factual questions
for the owner; propose required forms.

Cannot: answer the owner's questions, attest, sign, transmit a return, record an agency
receipt, or mark anything filed or accepted. Those are owner-only and enforced in the database.

## Human-readable documentation

- https://www.finance.fyi/connect — the three ways to connect, what a connected agent can and
  cannot do, and how the connection works.

## Machine-readable references

- OpenAPI for the same operations over REST: https://www.finance.fyi/api/openapi
- Capability registry (MCP tool): finance_os_get_capabilities
- Resume a tax filing (MCP tool): finance_os_resume_tax_filing