Menu de la documentation : MCP server

MCP server

Docs

AI agents can preview, issue and look up documents through Tallio’s MCP server. Its tools are the REST API’s own operations, called with your API key.

Sur cette page

What it is
Endpoint and keys
Connect a client
Limits
Tools

Remarque

Start with a test key (sk_test_…): nothing it issues is live. It uses the merchant’s test-mode connection, the provider’s own test environment, or Tallio’s sandbox when the merchant has none. Get a sandbox key.

What it is #

The Model Context Protocol (MCP) lets an AI client call outside tools. Tallio’s MCP server offers one tool per API operation an agent may use, named after it (preview_document, create_document, list_events). Each tool takes the operation’s fields as arguments and returns its result.

Every tool call goes through the REST API with your key, so an agent gets the same validation, errors and access as any other client. Operations that carry credentials, signing secrets or personal data are not tools: connecting a provider, creating a webhook endpoint or rolling its secret, a delivery’s responses, the tax-id lookup, a document’s PDF, erasure and the logs. Use the dashboard or the REST API for those.

Endpoint and keys #

The server is hosted at https://tallio.dev/api/mcp over Streamable HTTP. Send your API key as a Bearer token on every request, as with the REST API.

Test key (sk_test_…): never issues live. Documents go to the merchant’s test-mode connection, which reaches the provider’s test environment, or to Tallio’s sandbox when the merchant has no test connection.
Live key (sk_live_…): real documents, issued through the merchant’s provider. Give an agent a live key only when you mean it to issue.

The key decides the mode; there is no separate endpoint per mode. A missing or invalid key gets the API’s 401 error. Restricted store keys (rk_…) are refused with 403 restricted_key.

Connect a client #

Claude Code connects over HTTP directly. Set TALLIO_API_KEY to your key first.

Claude Code

claude mcp add --transport http tallio https://tallio.dev/api/mcp \
  --header "Authorization: Bearer $TALLIO_API_KEY"

Claude Desktop starts local servers from its config file, so it reaches a hosted server through the mcp-remote bridge, which adds the header. Put your key after Bearer.

claude_desktop_config.json

{
  "mcpServers": {
    "tallio": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://tallio.dev/api/mcp",
        "--header",
        "Authorization:${TALLIO_AUTH}"
      ],
      "env": {
        "TALLIO_AUTH": "Bearer sk_test_…"
      }
    }
  }
}

Cursor takes the URL and the header in its MCP config, globally or per project, and reads the key from TALLIO_API_KEY in your environment, so the file never holds it.

~/.cursor/mcp.json

{
  "mcpServers": {
    "tallio": {
      "url": "https://tallio.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TALLIO_API_KEY}"
      }
    }
  }
}

Any other client that speaks Streamable HTTP needs the URL and the Authorization header. To check a key, list the tools from a shell:

tools/list

curl https://tallio.dev/api/mcp \
  -H "Authorization: Bearer $TALLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Limits #

One message per request. Each POST carries one JSON-RPC message, so at most one tool call. A batch array is refused with HTTP 400 and the JSON-RPC error -32600.
No session. Every POST stands alone and answers with JSON. GET and DELETE answer 405, since there is no stream to open or session to close.
Shared rate limit. A POST counts as one request against your key’s REST API budget, whatever the tool does. Once the budget is spent, the POST gets the API’s 429 with RateLimit-* headers.
Safe retries. A tool that creates something sends an idempotency-key header derived from the tool and its arguments, so an agent’s retry returns the first result. To create a second identical document, change its external_reference.
Retries that repeat. A tool marked not safe to retry in the table below does its work again when called again: resend_webhook_delivery sends the event a second time. After a timeout, have the agent read the result (here list_webhook_endpoint_deliveries) before it calls the tool again.
Errors. A refused call comes back as a tool error whose text is the API’s error object, with its code, message and retryable. Unknown arguments are refused, so a misspelled field never goes unnoticed.

Tools #

Generated from the API’s operation registry, the same source the server registers its tools from.

Tallio MCP tools
Tool	What it does	Effect
`preview_document`	Preview a document	Reads only
`create_document`	Issue a document	Creates; a retry with the same arguments returns the first result
`list_documents`	List documents	Reads only
`get_document`	Retrieve a document	Reads only
`create_credit_note`	Credit a document	Creates; a retry with the same arguments returns the first result
`correct_document`	Correct a document	Creates; a retry with the same arguments returns the first result
`retry_document`	Retry a failed document	Changes; not safe to retry
`cancel_document`	Cancel a document	Destructive; not safe to retry
`create_merchant`	Create a merchant	Creates; a retry with the same arguments returns the first result
`list_merchants`	List merchants	Reads only
`get_merchant`	Retrieve a merchant	Reads only
`archive_merchant`	Archive a merchant	Destructive; not safe to retry
`unarchive_merchant`	Unarchive a merchant	Changes; not safe to retry
`list_merchant_connections`	List a merchant's connections	Reads only
`get_connection`	Retrieve a connection	Reads only
`verify_connection`	Verify a connection	Changes; not safe to retry
`disconnect_connection`	Disconnect a connection	Destructive; not safe to retry
`delete_connection`	Delete a connection	Destructive; safe to retry
`list_webhook_endpoints`	List webhook endpoints	Reads only
`get_webhook_endpoint`	Retrieve a webhook endpoint	Reads only
`update_webhook_endpoint`	Update a webhook endpoint	Changes; safe to retry
`delete_webhook_endpoint`	Delete a webhook endpoint	Destructive; safe to retry
`list_webhook_endpoint_deliveries`	List an endpoint's deliveries	Reads only
`resend_webhook_delivery`	Resend a webhook delivery	Changes; not safe to retry
`list_events`	List events	Reads only
`get_event`	Retrieve an event	Reads only