Skip to docs content

MCP server

Walkthrough: from connecting to a change

Every message an AI app sends to connect, find a book, read a report, preview a categorization and apply it, with made-up ids and figures.

Before you start

  • The app signs in with 42six first (see Connect your AI app), then sends every message as a POST to https://42six.ai/mcp with Authorization: Bearer and its access token. Changes need an app signed in this way that asked for changes and was approved for the book.
  • One JSON-RPC message per request. A batch is refused. A message without an id (a notification) is answered 202 with no body.
  • The server keeps no session between requests.
  • Every id, name and amount below is an example. Your books answer with their own.

1. Initialize

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-app",
      "version": "1.0.0"
    }
  }
}
Answer
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "fortytwosix",
      "version": "1.0.0"
    },
    "instructions": "Reads the books you approved and proposes changes to them. Start with list_books. Every change is a preview tool first: show the user its summary, and call apply_change with its plan_id only after the user confirms. Money is a decimal string. Dates are half-open [from, to). Pages carry next_cursor; pass it back as cursor."
  }
}

This is the answer for an app that may make changes. For an app that only reads, and for an API key, instructions is shorter.

The app then sends notifications/initialized, which is answered 202.

2. List the tools

Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

The answer is result.tools: each tool with its name, description and inputSchema. An app signed in with 42six sees list_books in place of list_entities, and the change tools when it may make changes.

3. Find the book

Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_books",
    "arguments": {}
  }
}
Answer
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\":[{\"entity_id\":\"00000000-0000-4000-8000-000000000001\",\"name\":\"Example Studio LLC\",\"kind\":\"business\",\"workspace\":\"Example Studio\"}]}"
      }
    ]
  }
}

Every tool answers this way: one text item holding the answer as JSON. Parse it to read the fields. The entity_id is what every other tool takes as entity.

4. Read the chart of accounts

Request
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_accounts",
    "arguments": {
      "entity": "00000000-0000-4000-8000-000000000001"
    }
  }
}
The text of the result, parsed
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000010",
      "code": "101000",
      "name": "Operating Checking",
      "type": "asset",
      "subtype": null,
      "parent_id": null,
      "is_bank": true,
      "is_active": true,
      "created_at": "2026-01-05T16:20:00.000000+00:00"
    },
    {
      "id": "00000000-0000-4000-8000-000000000011",
      "code": "742000",
      "name": "Software and Subscriptions",
      "type": "expense",
      "subtype": null,
      "parent_id": null,
      "is_bank": false,
      "is_active": true,
      "created_at": "2026-01-05T16:20:00.000000+00:00"
    }
  ],
  "next_cursor": null
}

A full page of 1,000 rows carries next_cursor. Pass it back as cursor for the next page.

5. Read a report

Request
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "income_statement",
    "arguments": {
      "entity": "00000000-0000-4000-8000-000000000001",
      "from": "2026-03-01",
      "to": "2026-04-01"
    }
  }
}
The text of the result, parsed
{
  "data": {
    "from": "2026-03-01",
    "to": "2026-04-01",
    "revenue": {
      "total": "1200.00",
      "accounts": [
        {
          "account_id": "00000000-0000-4000-8000-000000000012",
          "code": "401000",
          "name": "Sales",
          "amount": "1200.00",
          "subtype": null
        }
      ]
    },
    "cogs": {
      "total": "0.00",
      "accounts": []
    },
    "gross_profit": "1200.00",
    "operating_expenses": {
      "total": "49.00",
      "accounts": [
        {
          "account_id": "00000000-0000-4000-8000-000000000011",
          "code": "742000",
          "name": "Software and Subscriptions",
          "amount": "49.00",
          "subtype": null
        }
      ]
    },
    "operating_income": "1151.00",
    "other_income": {
      "total": "0.00",
      "accounts": []
    },
    "other_expenses": {
      "total": "0.00",
      "accounts": []
    },
    "net_income_before_separately_stated": "1151.00",
    "separately_stated_income": {
      "total": "0.00",
      "accounts": []
    },
    "separately_stated_expenses": {
      "total": "0.00",
      "accounts": []
    },
    "net_income": "1151.00"
  }
}

from is inclusive and to is exclusive, so this is March. Amounts are decimal strings; keep them as strings or exact decimals, never floating point.

6. Preview a change

Request
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "preview_categorize",
    "arguments": {
      "entity": "00000000-0000-4000-8000-000000000001",
      "item_ids": [
        "00000000-0000-4000-8000-000000000030"
      ],
      "account": "Software and Subscriptions"
    }
  }
}
The text of the result, parsed
{
  "plan_id": "00000000-0000-4000-8000-000000000070",
  "kind": "categorize",
  "summary": {
    "account": {
      "id": "00000000-0000-4000-8000-000000000011",
      "code": "742000",
      "name": "Software and Subscriptions",
      "type": "expense",
      "is_bank": false
    },
    "functional_class": null,
    "count": 1,
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000030",
        "date": "2026-03-14",
        "description": "EXAMPLE SOFTWARE CO",
        "bank_account": {
          "id": "00000000-0000-4000-8000-000000000010",
          "code": "101000",
          "name": "Operating Checking",
          "type": "asset",
          "is_bank": true
        },
        "direction": "money out",
        "account_side": "debit",
        "amount": "49.00",
        "cents": "4900"
      }
    ],
    "not_shown": 0,
    "not_shown_text": null,
    "totals": {
      "debit": {
        "amount": "49.00",
        "cents": "4900"
      },
      "credit": {
        "amount": "0.00",
        "cents": "0"
      }
    },
    "exclusions": [],
    "year_end_close_redone": false,
    "kind": "categorize",
    "book": {
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "Example Studio LLC"
    },
    "books_locked_through": "2026-02-28",
    "expires_at": "2026-04-02T14:10:00Z"
  },
  "expires_at": "2026-04-02T14:10:00Z"
}

Nothing has changed yet. Show the summary to the person, and once they confirm, apply the plan_id before expires_at, 10 minutes after the preview.

7. Apply it

Request
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "apply_change",
    "arguments": {
      "plan_id": "00000000-0000-4000-8000-000000000070"
    }
  }
}
The text of the result, parsed
{
  "plan_id": "00000000-0000-4000-8000-000000000070",
  "kind": "categorize",
  "result": {
    "count": 1
  },
  "request_id": "00000000-0000-4000-8000-000000000080",
  "replayed": false
}

Sending the same apply_change again, after a dropped connection for example, answers the same result with replayed set to true. The books change once.

When something is refused

A wrong argument is a JSON-RPC error. Here income_statement was called without from:

Answer
{
  "jsonrpc": "2.0",
  "id": 8,
  "error": {
    "code": -32602,
    "message": "from is required."
  }
}

A change the books refuse is a tool result with isError set. Here the plan was applied more than 10 minutes after its preview:

Answer
{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"plan_expired\",\"error_description\":\"This preview has expired; preview again.\"}"
      }
    ],
    "isError": true
  }
}
  • An access token that has expired is answered HTTP 401: refresh it and send the message again.
  • HTTP 429 carries Retry-After: wait that many seconds.
  • HTTP 503 carries Retry-After 2: the read could not be recorded, so it was not served. Send it again.
  • Limits and errors lists every code.