# AI Assistant Integration

Connect your ledger to AI assistants like Claude, Cursor, and VS Code Copilot using the Model Context Protocol (MCP).

Once configured, you can interact with your ledger using natural language — check balances, create transactions, query ledgers, and run integrity checks directly from your AI assistant.

***

## Prerequisites

* [Node.js](https://nodejs.org) installed (v18 or later)
* A running ledger instance
* API credentials (`api_key` and `api_secret`) — generated during onboarding or via the Console

***

## Installation

```bash
npm install -g entrytarget-mcp
```

***

## Configuration

Add the following to your AI assistant's MCP configuration file. Replace the values with your own credentials and ledger URL.

```json
{
  "mcpServers": {
    "ledger": {
      "command": "npx",
      "args": ["entrytarget-mcp"],
      "env": {
        "LEDGER_URL": "https://your-ledger-host:8080",
        "LEDGER_API_KEY": "ak_...",
        "LEDGER_API_SECRET": "sk_..."
      }
    }
  }
}
```

### Where to place this file

| Assistant                | Config file location                                              |
| ------------------------ | ----------------------------------------------------------------- |
| Claude Desktop (macOS)   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
| Cursor                   | Settings → MCP Servers                                            |
| VS Code (Copilot)        | Settings → MCP Servers                                            |

If your assistant already has other MCP servers configured, add the `"ledger"` entry inside the existing `"mcpServers"` object.

***

## Available Commands

Once connected, your AI assistant can perform the following operations:

| Operation          | What you can ask                                        |
| ------------------ | ------------------------------------------------------- |
| **Accounts**       | "Create a BRL account with category PAYMENT\_ACCOUNT"   |
|                    | "What's the balance of account `abc-123`?"              |
|                    | "Show me the ledger for account `abc-123` from January" |
|                    | "Show total balances for BRL grouped by category"       |
| **Transactions**   | "Transfer 5000 from account A to account B as PIX\_OUT" |
|                    | "Show me the journal entries for transaction `xyz-789`" |
| **Integrity**      | "Run an integrity check"                                |
| **Ledger Archive** | "Archive ledger lines before 2026-01-01"                |
|                    | "Show archived ledger for account `abc-123`"            |
| **Recovery**       | "Are there any recovery records from the last restart?" |
|                    | "Look up idempotency key `my-key-123`"                  |

These are examples — you can phrase your requests however you like. The assistant understands the context and picks the right operation.

***

## Security Notes

* Your API credentials are stored locally on your machine, in the config file. They are never sent to the AI provider.
* All communication between the MCP server and your ledger uses your existing API authentication (`X-Api-Key` + `X-Api-Secret` headers).
* The MCP server runs as a local process on your machine — it does not expose any ports or accept incoming connections.

***

## Troubleshooting

**"Command not found" when starting the assistant** Make sure Node.js is installed: `node --version`. If not, install it from [nodejs.org](https://nodejs.org).

**Connection refused** Verify that `LEDGER_URL` is reachable from your machine. If your ledger runs in AWS, you may need a VPN or SSH tunnel.

**Authentication errors (401)** Double-check your `LEDGER_API_KEY` and `LEDGER_API_SECRET`. You can test them directly:

```bash
curl -H "X-Api-Key: ak_..." -H "X-Api-Secret: sk_..." https://your-ledger-host:8080/health
```

**Assistant doesn't see the ledger tools** Restart your AI assistant after editing the config file. Most assistants only read the config at startup.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://entrytarget.gitbook.io/docs/ai-assistant-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.