inio-mcp

Model Context Protocol (MCP) server for the Inio REST API. Connect AI assistants such as Claude, Cursor or VS Code to your own Inio data: customers, invoices, pauses, retry attempts and payments.

Status: 0.7.0. Read-only by default, with opt-in write tools; stdio or a shared HTTP server. Published as @dnmitev/inio-mcp until it moves to the @inio scope.

Install

You need Node.js 24 or later and Inio API client credentials (OAuth2 client credentials for your Inio API realm).

export INIO_CLIENT_ID=...       # your Inio API client id
export INIO_CLIENT_SECRET=...   # your Inio API client secret
export INIO_AUTH_URL=...        # token endpoint (or realm issuer URL) of your Inio API realm
export INIO_URL=...             # Inio API gateway base URL, including /v1
npx -y @dnmitev/[email protected]

Quick start (Claude Desktop)

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json) and restart Claude Desktop:

{
  "mcpServers": {
    "inio": {
      "command": "npx",
      "args": ["-y", "@dnmitev/[email protected]"],
      "env": {
        "INIO_CLIENT_ID": "your-client-id",
        "INIO_CLIENT_SECRET": "your-client-secret",
        "INIO_AUTH_URL": "https://<your-keycloak>/realms/<realm>/protocol/openid-connect/token",
        "INIO_URL": "https://<your-inio-api-gateway>/v1"
      }
    }
  }
}

The file holds the client secret in plaintext; keep it readable only by you (chmod 600). Then ask, for example: "Which open invoices does customer C-1001 have?" More prompts: examples.

Set up your client

Each guide covers running the server locally (npx), in Docker, and connecting to a hosted team server:

Claude on the web, Desktop and mobile can use a hosted server as a connector, with your own sign-in and nothing installed: docs/setup/claude-web.md.

To run one server for your whole team, see Hosting a shared server.

Inio clients who want to run it in their own cloud or agent platform, with their own Inio API credentials: Self-hosting for Inio clients.

Pinning and verification

The examples pin version 0.7.0. Change the version on purpose when you upgrade; do not drop it. The pin covers the package itself: npx still resolves its dependencies within their declared ranges on each fresh install.

• npm: the package is published with npm provenance. The Provenance section on the package's npmjs.com page shows the source repository and workflow that built it; npm view @dnmitev/[email protected] dist.attestations gives the URL of the attestation bundle that records them. npm audit signatures, run in a project that installed the package (for example npm init -y && npm i --ignore-scripts @dnmitev/[email protected] && npm audit signatures), checks the registry signatures and provenance attestations of everything installed.
• Docker: look up the digest with docker buildx imagetools inspect ghcr.io/dnmitev/inio-mcp:0.7.0 and use ghcr.io/dnmitev/inio-mcp@sha256:<digest>. Pinning the digest stops the tag from changing under you; it does not by itself prove who built the image.

Tools

These tools are read-only. Results are compacted (empty values dropped). Redaction depends on the customer type: business customers (B) have only invoice links and SSNs redacted; consumers (C) and unknown types also have contact details, address, city, name, references, SSNs and bank details redacted. INIO_REVEAL_PII=true turns it off. See Data protection for the exact lists.

Options on the detail tools:

• get_invoice takes withInherited to add inherited values (IBAN, bank, effective pause). With an invoice number this makes two API calls.
• get_invoice and get_customer take includeWorkflowSettings to add workflowsSettings (distribution method, escalation fees and timing, enabled stages). It is large, so it is off by default.

If the Inio API rate-limits a request (HTTP 429), the server waits for Retry-After (at most 5 s) and retries once; a second 429 is returned as RATE_LIMITED.

Write tools (opt-in)

Write tools are registered only when the server runs with INIO_ALLOW_WRITES=true. They are marked as destructive, so MCP clients can ask you to confirm each call (Claude Desktop does unless you allow the tool permanently). Every write is recorded in Inio's audit fields as inio-mcp. The Inio API has no roles for API clients: with writes enabled, anything these tools can do is allowed for your credentials. To narrow it, list only the tools you need in INIO_WRITE_TOOLS and cap payments with INIO_MAX_PAYMENT_AMOUNT.

Do not permanently allow (auto-approve) write tools in your client. The confirmation step is where you catch a wrong amount, customer or date before it reaches Inio.

If a write times out, cannot reach the API or gets a server error (HTTP 5xx), the change may or may not have been applied, and the result says to check the customer or invoice before trying again. If the API accepts a write but its answer cannot be read, the tool reports success with a note to check before retrying.

Not available: reversing a payment (the public API does not expose the payment allocation ids that reversal needs) and creating invoices (creating one sends it to the end customer at once). Use the Inio back office for these.

Logs

The server writes JSON log lines to stderr (stdout carries the MCP protocol). Claude Desktop saves them to ~/Library/Logs/Claude/mcp-server-inio.log. Each tool call logs its duration, outcome, approximate token cost (approxTokens) and the MCP client that called it (name and version, for example Claude Desktop; over HTTP only when the client sends it with each request). Write calls also log write: true and the identifiers they changed (target: customer, invoice, credit invoice or pause id or number); amounts, contact details and other arguments are not logged. The startup line lists the registered write tools and the payment limit. Set INIO_LOG_LEVEL=debug to also see every API call and token refresh. Secrets and tokens are never logged.

Troubleshooting

Data protection

What the server redacts from tool results (unless INIO_REVEAL_PII=true) depends on the customer type (customerType). Each object in a result uses its own type; an object without one (an invoice, a pause) follows the object it sits in.

Business customers (B). Company and contact details are business data, often public, so only the invoice links (anyone holding the link can open the invoice) and a personal identity number (a sole trader's SSN) are redacted:

• pdfURL, digitalInvoiceURL, ssn

Consumers (C) and unknown types. A private person's details are personal data:

• any field whose name contains email (e.g. distributionEmailAddress), and email addresses inside any text
• any field whose name contains phone (e.g. mobilePhoneNo)
• address lines: addressLine, addressLine1, addressLine2, …
• zipCode, city
• customerName, yourReference
• ssn
• iban, bankAccount, accountNumber
• invoice links: pdfURL, digitalInvoiceURL

Invoices carry no customer type, so get_invoice looks up the invoice's customer once (cached until the server restarts, so a customer whose type changes keeps the old rules until then) and uses consumer rules if that lookup fails. Invoices returned by write tools always use consumer rules.

Error messages always hide email addresses, and the per-field error messages for the consumer fields listed above (for both customer types), even with INIO_REVEAL_PII=true. Other error text is returned as the API gives it. Everything else is returned as the API gives it, including organisation and VAT numbers, notes and other free text, invoice descriptions, amounts and invoice stages.

• Tool results go to the LLM provider behind your assistant (for example Anthropic for Claude, or the model provider you chose in Cursor or VS Code). Your organisation needs a data processing agreement with that provider that covers your customers' data.
• Arguments of write tools, such as the SSN, contact details and addresses in create_customer and update_customer, are in your prompt and in the tool call. They reach the provider whatever INIO_REVEAL_PII says.
• The server stores nothing. It keeps the Inio access token in memory only.
• Logs (stderr) contain tool names, durations and outcomes. Failed API calls are logged with their path, which can include a customer or invoice number or id; at debug level every API call is. Logs never contain tokens, secrets or tool results.

Release model

inio-mcp has a single maintainer. Releases are published only by the GitHub Actions release workflow, from version tags: it publishes to npm with provenance and pushes the image to GHCR. See Pinning and verification for how to check a release. The package moves to the @inio scope and the company GitHub organisation later; the README will say when.

Development

To run from source, clone the repository, run npm ci && npm run build, and point your client at node /absolute/path/to/iniomcp/dist/index.js.

License

Apache License 2.0. The license covers this source code only. It does not grant access to the Inio API; you need your own Inio API credentials.