MCP Server (AI Integration)

BeeKeeper exposes a Model Context Protocol (MCP) server that allows AI assistants like Claude to query your financial data. The server is read-only — AI agents can view accounts and journal entries but cannot modify any data.

Authentication

All MCP requests require an API key passed as a Bearer token in the Authorization header:

Authorization: Bearer your-api-key

API keys are validated against the FutureFund accounts service. Visit https://accounts.futurefund.com/users/api_keys to create an API key.

Endpoint

The MCP server is available at:

POST https://beekeeper.futurefund.com/mcp/messages

This endpoint accepts JSON-RPC 2.0 requests per the MCP specification.

Available Tools

list_organizations

List organizations you have access to. Returns only organizations associated with your API key. Call this first to get the uuid needed for other tools.

Parameters: None

Returns: Array of organizations

[
  {
    "uuid": "abc123def456",
    "name": "Lincoln Elementary PTA",
    "legal_name": "Lincoln Elementary Parent Teacher Association",
    "organization_type": "pta",
    "fiscal_start_month": 7
  }
]

list_accounts

List the chart of accounts for an organization.

Parameters:

Name	Type	Required	Description
`organization_uuid`	string	Yes	UUID from `list_organizations`
`account_type`	string	No	Filter: `asset`, `liability`, `equity`, `income`, `expense`
`active_only`	boolean	No	Only active accounts (default: `true`)

Returns: Array of accounts

[
  {
    "id": 1,
    "code": "1000",
    "name": "Checking",
    "account_type": "asset",
    "balance": 5432.10,
    "active": true
  }
]

get_account

Get detailed information about a single account.

Parameters:

Name	Type	Required	Description
`organization_uuid`	string	Yes	UUID from `list_organizations`
`account_id`	integer	Yes	Account ID from `list_accounts`

Returns: Account details

{
  "id": 1,
  "code": "1000",
  "name": "Checking",
  "account_type": "asset",
  "balance": 5432.10,
  "active": true,
  "institution": "Wells Fargo",
  "last_reconciled_balance": 5200.00,
  "last_reconciled_date": "2025-11-30",
  "transaction_count": 47
}

Returns { "error": "Account not found" } if the account does not exist.

list_journal_entries

List journal entries with optional filtering by date range and account.

Parameters:

Name	Type	Required	Description
`organization_uuid`	string	Yes	UUID from `list_organizations`
`start_date`	string	No	Start date (`YYYY-MM-DD`). Defaults to current fiscal year start.
`end_date`	string	No	End date (`YYYY-MM-DD`). Defaults to current fiscal year end.
`account_id`	integer	No	Filter to entries that include this account
`limit`	integer	No	Max entries to return (default: 50, max: 200)

Returns: Array of journal entries with line items

[
  {
    "id": 10,
    "transacted_on": "2025-08-15",
    "payee": "Membership Payment - Jones",
    "description": "Annual membership dues",
    "reference_number": "1001",
    "voided": false,
    "items": [
      {
        "account_name": "Checking",
        "account_code": "1000",
        "debit": 25.00,
        "credit": 0.00
      },
      {
        "account_name": "Membership Dues",
        "account_code": "4000",
        "debit": 0.00,
        "credit": 25.00
      }
    ]
  }
]

get_journal_entry

Get full details of a single journal entry including vendor and activity.

Parameters:

Name	Type	Required	Description
`organization_uuid`	string	Yes	UUID from `list_organizations`
`journal_entry_id`	integer	Yes	Entry ID from `list_journal_entries`

Returns: Full journal entry

{
  "id": 10,
  "transacted_on": "2025-08-15",
  "payee": "Office Supplies Co.",
  "description": "Purchase of office supplies",
  "reference_number": "1001",
  "voided": false,
  "vendor": "Office Supplies Co.",
  "activity": "Back to School Night",
  "items": [
    {
      "account_id": 1,
      "account_name": "Checking",
      "account_code": "1000",
      "account_type": "asset",
      "debit": 0.00,
      "credit": 150.00
    },
    {
      "account_id": 5,
      "account_name": "Office Supplies",
      "account_code": "5000",
      "account_type": "expense",
      "debit": 150.00,
      "credit": 0.00
    }
  ],
  "created_at": "2025-08-15T10:30:00Z",
  "updated_at": "2025-08-15T10:30:00Z"
}

Returns { "error": "Journal entry not found" } if the entry does not exist.

Typical Workflow

An AI agent interacting with BeeKeeper follows this pattern:

Authenticate — include the API key in every request
List organizations — call list_organizations to discover available orgs and get their UUIDs
Query data — pass the organization_uuid to list_accounts, list_journal_entries, etc.

Agent: list_organizations
  → Gets [{ uuid: "abc123", name: "Lincoln PTA", ... }]

Agent: list_accounts(organization_uuid: "abc123")
  → Gets chart of accounts with balances

Agent: list_journal_entries(organization_uuid: "abc123", start_date: "2025-07-01")
  → Gets recent transactions

Connecting an MCP Client

Claude Desktop

Add to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "beekeeper": {
      "url": "https://beekeeper.futurefund.com/mcp/messages",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Claude Code

Run the following command:

claude mcp add beekeeper --transport http https://beekeeper.futurefund.com/mcp/messages --header "Authorization: Bearer your-api-key"