AI assistants (MCP)

Annuva contains a Model Context Protocol server. MCP is the open standard AI assistants use to call tools – with it, your assistant can read your dashboard, create invoice drafts, run the billing run or book a fixed cost, just by being asked.

• Endpoint: https://<your-annuva>/api/mcp
• Transport: Streamable HTTP (stateless)
• Authentication: the same personal API tokens as the REST API: Authorization: Bearer an_…
• Tools: 78 – everything the REST API can do

1. Create a token#

In Annuva open Profile → API tokens and create a token:

• read – the assistant can analyse, but never change anything. Only the read-only tools are visible. Recommended to start with.
• read_write – the assistant can also create, change and delete data and run actions such as issuing invoices.

The token has the permissions of your user. Tools for settings, templates and users are only available with an admin account.

2. Connect your client#

Claude Code#

claude mcp add --transport http annuva https://annuva.example.com/api/mcp \
    --header "Authorization: Bearer an_…"

Check the connection with claude mcp list, then simply ask in your session.

Claude Desktop#

Claude Desktop starts local MCP servers from its configuration file (Settings → Developer → Edit Config). The small bridge mcp-remote connects it to the HTTP endpoint (requires Node.js):

{
    "mcpServers": {
        "annuva": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://annuva.example.com/api/mcp",
                "--header",
                "Authorization:${ANNUVA_AUTH}"
            ],
            "env": {
                "ANNUVA_AUTH": "Bearer an_…"
            }
        }
    }
}

Restart Claude Desktop afterwards; Annuva appears in the tools menu.

Cursor#

In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
    "mcpServers": {
        "annuva": {
            "url": "https://annuva.example.com/api/mcp",
            "headers": {
                "Authorization": "Bearer an_…"
            }
        }
    }
}

VS Code#

In .vscode/mcp.json – VS Code asks for the token on first use and stores it securely:

{
    "inputs": [
        {
            "type": "promptString",
            "id": "annuva-token",
            "description": "Annuva API token",
            "password": true
        }
    ],
    "servers": {
        "annuva": {
            "type": "http",
            "url": "https://annuva.example.com/api/mcp",
            "headers": {
                "Authorization": "Bearer ${input:annuva-token}"
            }
        }
    }
}

Other clients#

Every client that supports Streamable HTTP with a custom Authorization header works the same way: URL https://<your-annuva>/api/mcp, header Authorization: Bearer an_….

3. Ask#

You don't need to know the tool names – describe what you want:

• "How did this year go compared to last year?"
• "Which customers cost me more than they bring in?"
• "Create the yearly hosting invoices for all customers and show me the drafts."
• "Which domains and contracts renew in the next 60 days?"
• "Book last month's server bill of €38.90 as a fixed cost."
• "Remind all customers whose invoices are more than 14 days overdue."

Good to know#

• Money values in the entity tools are decimals in your currency; the dashboard tools return integer cents.
• Issued invoices cannot be changed by anyone – the assistant can only cancel them, which creates a cancellation invoice.
• Let the assistant show you drafts before you issue or send them. Most clients ask for confirmation before a tool changes data.
• Everything the assistant reads is sent to the provider of your AI model. Use a read token if you only need analysis, and check what your provider does with the data.

All tools#

Tools starting with list_ or get_ only read; all others change data and need a read_write token.