MCP server

Alya Books exposes its API as a Model Context Protocol server. Every tool maps onto one REST route, so validation, permissions and behaviour are identical to the API.

Endpoint

POST https://api.alyabooks.ai/api/v1/mcp

Transport: Streamable HTTP, stateless. Requests are JSON-RPC 2.0 messages (single or batched); responses are JSON. The server never opens a server-sent events stream, so GET /mcp answers 405.

Headers on every request:

Content-Type: application/json
Accept: application/json
X-API-KEY: sk_live_…
X-Organization-Id: <client id>   (optional, CA firms)

Authentication is the same API key as the REST API; a tool is only callable when the key has its scope (invoices:write, incoming:read, webhooks:manage, …). Test keys make the assistant work on test documents.

Connect from claude.ai or ChatGPT (sign-in)

Chat apps that add MCP servers as custom connectors cannot send an API key, so the endpoint also supports OAuth 2.1, the way the MCP specification describes:

1. In Claude (Settings → Connectors → Add custom connector) or ChatGPT (connectors in developer mode), enter the MCP URL: https://<your API host>/functions/v1/api-v1/mcp (https://api.alyabooks.ai/api/v1/mcp once the API domain is live).
2. The app registers itself and opens Alya Books's sign-in. After signing in, you choose the organisation, Test or Live and the permissions, then click Allow.
3. The app receives a one-hour access token and a refresh token; it refreshes on its own. Revoke it any time under API access → API keys → Connected apps.

What the server publishes, for client developers:

Access tokens (oat_…) work on /mcp only; the REST API keeps using API keys. A token belongs to one organisation, so X-Organization-Id cannot switch it. Clients that only look for discovery documents at the host's root, rather than under the API's path, need the API domain to forward /.well-known/… to the API.

Connect a client with an API key

{
"mcpServers": {
  "alyabooks": {
    "type": "http",
    "url": "https://api.alyabooks.ai/api/v1/mcp",
    "headers": { "X-API-KEY": "sk_live_…" }
  }
}
}

{
"mcpServers": {
  "alyabooks": {
    "url": "https://api.alyabooks.ai/api/v1/mcp",
    "headers": { "X-API-KEY": "sk_live_…" }
  }
}
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL("https://api.alyabooks.ai/api/v1/mcp"), {
requestInit: { headers: { "X-API-KEY": process.env.ALYABOOKS_API_KEY! } },
});
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
const { tools } = await client.listTools();
const result = await client.callTool({ name: "list_invoices", arguments: { status: "accepted", perPage: 5 } });

curl -X POST https://api.alyabooks.ai/api/v1/mcp -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_account", "arguments": {} } }'

Claude Code: claude mcp add --transport http alyabooks https://api.alyabooks.ai/api/v1/mcp --header "X-API-KEY: sk_live_…".

Tools

149 tools in 17 groups: 72 only read, the rest change data. Tool descriptions state their scope; tools/list returns full JSON Schemas for the arguments and the annotations below.

Marked destructive (destructiveHint, so clients ask before running them): submit_invoice, send_invoice, delete_draft_invoice, delete_import, delete_customer, delete_contact_person, delete_contact_address, delete_product, delete_bundle, delete_price_list, delete_webhook, delete_custom_field, delete_field_template, delete_project, delete_recurring_invoice, reopen_vat_return, send_erp_message, replay_erp_message. Submitting, sending and replaying reach the FTA or a buyer and cannot be undone; deletes remove data. The dry runs (dry_run_invoice, dry_run_erp_message) are marked read-only: they store nothing.

Test or live. Every tools/call result carries _meta: { "einvoicing/environment": "test" } or "live", from the key in use. With a test key nothing reaches the live service provider.

Not available to assistants, on purpose: API keys, team members, the service-provider connection, the company profile, and the adviser's sign-off on an ERP charge map. Those are set in the app by the people responsible.

Tool results contain the API response as text and as structuredContent; API errors are returned as tool results with isError: true and the usual { code, statusCode, message, extra } envelope, with each validation error's path, explanation and fix, so the assistant can correct its input.

Resources

Example: a CargoWise message from a chat

"Here is a UniversalTransaction from our CargoWise UAT. Check it, tell me what fails, fix our charge map and send it."

The assistant calls dry_run_erp_message with the XML and reads the mapping notes and failed rules (for example "Charge PSC has no mapping"). It proposes the mapping, calls update_erp_connector after you agree, runs the dry run again until it is valid, then calls send_erp_message. With a live key, send_erp_message is marked destructive, so the client asks you before it runs. If the message had already failed in the log, replay_erp_message processes it again instead.

Example conversation

"Create a tax invoice for Buyer LLC (TRN 100000000000011) for 10 consulting hours at AED 500, due in 30 days, submit it and tell me when the FTA accepts it."

The assistant calls create_tax_invoice with submit: true, reads validation and submission from the result, then polls get_invoice_status until invoiceStatus is accepted or rejected. With a webhook on invoice.reported your own system learns about it at the same moment.

Limits

• Stateless: no sessions, no subscriptions, no server-initiated messages. Prompts are not provided (prompts/list is empty).
• Same rate limit as the API (600 requests per minute per key).
• download_invoice with format: "pdf" returns a download link (url, expiresAt, filename) that works for 15 minutes without a key, so an assistant can hand the PDF to the user instead of a very long base64 string. delivery: "inline" returns the base64 instead, and delivery: "link" gives a link for XML or HTML too. XML and HTML come back as text by default; get_import_source returns binary files as base64 in structuredContent.