Developer API · MCP

Connect your assistant to Blackbird.

Blackbird is an MCP server with its own sign-in. Paste the address into ChatGPT, Claude or any MCP client and it will send you here to sign in and approve — no key to copy, nothing to paste into a config file. Then ask in your own words: who still owes me money, what is my GST for September, is my month closed. For a script or a spreadsheet there are API keys and plain HTTP instead. Everything is read and prepared; nothing is filed, posted or confirmed without you.

The address, for anything that asks for one: https://www.blackbirdfinance.net/api/mcp

Two ways in, and which to use

Connect (OAuth)

For an assistant used by a person: ChatGPT, Claude, Claude Code, anything with a Connect button. The client registers itself, sends you here, you sign in and approve, and it gets a token that expires every hour and renews itself. Nothing is pasted anywhere, and you can disconnect it from Settings at any time.

An API key

For a script, a spreadsheet, a cron job or a workflow tool — anything with no person in front of it. Make one in Settings → Developer API; it is shown once, looks like bbf_live_…, and lasts until you revoke it.

What the Connect button does

Blackbird is its own OAuth 2.1 authorization server, so a client discovers everything it needs from the address alone. There is nothing for you to configure, and nothing for us to approve first.

  • Discovery: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server
  • Registration: a Client ID Metadata Document, or dynamic registration at /api/oauth/register
  • Authorization code with PKCE (S256 only), resource indicator bound to the MCP endpoint, iss on every response
  • Scopes: blackbird:read, and blackbird:write only for run_month_close
  • Access tokens last an hour; refresh tokens rotate, and a replayed one revokes the whole connection

Claude Code

One command, in any project. It opens a browser to approve:

claude mcp add --transport http blackbird https://www.blackbirdfinance.net/api/mcp

Or with a key instead, if you would rather not sign in:

claude mcp add --transport http blackbird https://www.blackbirdfinance.net/api/mcp \
  --header "Authorization: Bearer bbf_live_YOUR_KEY"

Then ask it something: “what do my clients owe me, and what is overdue?” Claude Code lists the tools with /mcp.

Claude desktop and claude.ai

Settings → Connectors → Add custom connector, then paste https://www.blackbirdfinance.net/api/mcp and press Connect. Blackbird’s sign-in opens, you approve, and the tools appear. No key, no config file, no header field needed.

A client that wants a configuration file instead can hold a key directly. The server is stateless streamable HTTP on a single POST endpoint, so nothing else needs configuring:

{
  "mcpServers": {
    "blackbird": {
      "type": "http",
      "url": "https://www.blackbirdfinance.net/api/mcp",
      "headers": { "Authorization": "Bearer bbf_live_YOUR_KEY" }
    }
  }
}

ChatGPT

In ChatGPT on a computer, open Settings → Connectors → Create (developer mode, on a paid plan), then:

  • Name: Blackbird Finance
  • MCP server URL: https://www.blackbirdfinance.net/api/mcp
  • Authentication: OAuth. Leave the client id and secret empty — Blackbird registers the connector itself.

Blackbird exposes the search and fetch pair ChatGPT looks for, so deep research and chat can both cite your own records.

The tools

  • search

    Find invoices, clients, documents and purchases by name or number.

  • fetch

    Open one record in full, by the id search gave back.

  • list_invoices

    Invoices newest first, with what is still owed on each.

  • outstanding_invoices

    Who owes what, split into not yet due and overdue.

  • gst_position

    A month’s GST from recorded invoices and purchases, by the GSTR-3B tables.

  • month_close

    The last month-close brief: what Blackbird prepared and checked, and what still needs you.

  • run_month_close

    Work out a month close now and record the brief. The one tool that writes anything.

  • due_dates

    Filing and tax dates coming up or already past.

  • list_clients

    Your clients, with country and GSTIN where recorded.

Plain HTTP, for everything else

The same answers, as JSON, with the key in a header. Reads need a read key; the one endpoint that records anything needs write.

curl -H "Authorization: Bearer bbf_live_YOUR_KEY" \
  https://www.blackbirdfinance.net/api/v1/outstanding
  • GET /api/v1/invoices?status=Outstanding&limit=50

    Invoices, filtered by status or issue date.

  • GET /api/v1/outstanding

    Receivables in total and per client.

  • GET /api/v1/gst-position?period=2026-09

    The month’s GST position for one GSTIN.

  • GET /api/v1/month-close?period=2026-09

    The last month-close brief.

  • POST /api/v1/month-close

    Work the close out now and record the brief. The one write; needs a write key.

  • GET /api/v1/due-dates?days=45

    The compliance calendar ahead.

  • GET /api/v1/clients

    Your clients.

  • GET /api/v1/search?query=ACME

    Ids to pass to /api/v1/record.

  • GET /api/v1/record?id=invoice:0b5f…

    One record in full.

What it will not do

No key and no connected app can file a GST return or export declaration, post a journal entry, confirm a payment match, send an invoice, change or delete a record, or make a payment. Eight of the nine tools only read. The ninth, run_month_close, writes one thing: the brief it has just worked out, in your own account. Every step that commits something stays in Blackbird, behind your own sign-in and second factor. Treat prepared numbers as preparation to check, not as a filing and not as advice.

What we keep, and for how long

  • Not your conversation. Blackbird stores the request a tool made and which account it was for. No prompt text, no reply, nothing else from the assistant.
  • Keys and tokens as hashes. An API key is stored as its SHA-256 and a six-character prefix. Tokens the same. The secret itself is never written down, by us or anyone.
  • Short-lived access. An access token lasts an hour; a refresh token lasts thirty days and is replaced every time it is used. A replayed one ends the whole connection.
  • Your records go to the app you connected, and nowhere else. What that app does with them is then its own company’s business, which is why the approval screen names it.
  • Ending it. Revoke a key or disconnect an app in Settings and it stops on the next request. Erasing your account erases its keys and connections too.

The full detail is in the Privacy Notice, section 8. Questions, or something not working: support@blackbirdfinance.net.

Questions

What can an assistant do with my Blackbird account?

Read it, and prepare. A read key can look at your invoices, clients, purchases, documents, GST position, compliance dates and month-close briefs. A write key can additionally ask Blackbird to work out a month close and record the brief. No key can file a return, post a journal entry, confirm a payment match, send an invoice or change a record. Those stay inside Blackbird, with you.

Do I need a key at all?

Not for an assistant. Paste the MCP address into ChatGPT, Claude or Claude Code and it will send you to Blackbird to sign in and approve; it then holds a token that expires hourly and renews itself. A key is for things with no person in front of them: a script, a cron job, a spreadsheet.

Where do I get a key?

Settings → Developer API, inside your account. Name the key after whatever will use it, and copy it when it is shown: Blackbird keeps only a hash, so it cannot be shown again. If you lose it, revoke it and make another.

How do I disconnect an app?

Settings → Developer API lists every app you have connected, with when it was connected and when it last read anything. Disconnect ends every token it holds on the next request. Revoking a key works the same way.

What does approving actually give the app?

A token for this one endpoint, carrying the scopes you saw on the approval screen, valid for an hour at a time. It is bound to Blackbird as its audience, so it is useless anywhere else, and it never contains your password or your second factor.

Does my data go to Anthropic or OpenAI?

Only what your assistant asks for, when you ask it. Blackbird answers the request; your assistant is the one that sees the answer, under its own provider’s terms. Blackbird does not send anything to a model on its own in this flow.

Is it the same API behind the MCP server?

Yes. The MCP tools and the REST endpoints run the same code over the same records, so a script and an assistant see the same numbers.

What happens if I revoke a key?

It stops working on the next request. Nothing else changes, and your other keys keep working.

Is there a sandbox?

Not yet. A read key on your own account is safe to experiment with: nothing it can call changes a record.