# MCP — connect an AI agent

Boya provides a **Model Context Protocol (MCP)** server so AI agents and assistants can
work with your Boya data safely. The MCP server is a thin, governed layer over the v2
API: every tool call is authenticated and scope-checked exactly like a REST call.

## Endpoint

```
https://api.boyahq.com/v2/mcp
```

The server speaks MCP over Streamable HTTP and authenticates with the **same OAuth2
client credentials** as the REST API.

## Connect

Add Boya as a remote MCP server in your MCP-compatible client (e.g. Claude Desktop /
Claude Code). Example configuration:

```json
{
  "mcpServers": {
    "boya": {
      "url": "https://api.boyahq.com/v2/mcp",
      "auth": {
        "type": "oauth2_client_credentials",
        "token_url": "https://api.boyahq.com/v2/oauth/token",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}
```

## Tools

Tools are generated from the v2 API and are **read-first**. Which tools appear depends on
your client's granted scopes:

| Tool | Scope required | Notes |
|  --- | --- | --- |
| `list_expenses`, `get_expense` | `expenses:read` |  |
| `list_transactions`, `get_transaction` | `transactions:read` |  |
| `get_account_balance` | `accounts:read` |  |
| `list_bills`, `get_bill` | `bills:read` |  |
| `list_vendors`, `list_customers` | `vendors:read`, `customers:read` |  |
| `get_fx_rate` | `fx:read` |  |
| `create_payout` | `payments:write` | **off by default** (private label) |
| `allocate_funds` | `employees:write` | **off by default** |


**Write tools and money movement are opt-in.** They are only registered when your API
client has the matching scope (and entitlement for private-label domains). An agent
cannot move money unless you have explicitly enabled it. Private-label tools are hidden
entirely from clients without the entitlement.

## Safety guidance

- Issue a **dedicated, least-privilege API client** for agent use — typically read-only.
- Keep money-movement scopes off unless an agent genuinely needs them, and pair them with
Boya's approval mandates so writes still require human authorization server-side.
- All MCP activity is subject to the same [rate limits](/v2/rate-limits) and audit
logging as REST.