Skip to content
Space Invoices Documentation

MCP Server

Space Invoices exposes its API as an MCP server at https://eu.spaceinvoices.com/mcp.

Use it when you want an AI assistant to work against your real Space Invoices account using the same API capabilities that power the REST integration: creating invoices, looking up customers, listing items, checking document state, and more.

What It Supports

  • Public JSON API operations from the main Space Invoices API
  • Existing bearer authentication
  • Optional per-tool account and entity scoping
  • The same validation, permissions, and middleware stack as normal API requests

What It Does Not Expose

  • PDF, HTML, file download, and other binary-response endpoints
  • Internal cron, admin, webhook receiver, and other non-public routes
  • Separate MCP-only actions that bypass the REST API

Endpoint

https://eu.spaceinvoices.com/mcp

Transport:

  • Streamable HTTP
  • Stateless
  • Bearer auth required

Authentication

Authenticate to the MCP endpoint with the same bearer tokens you already use for the API.

Recommended option:

  • Entity API key (ek_*) for single-business setups
  • Account API key (sk_*) for multi-entity setups where the client needs to choose entities

Also supported:

  • User access tokens, if your MCP client can send bearer headers

Example header:

Authorization: Bearer ek_sandbox_...

Tool Inputs

Each MCP tool is generated from an API operation.

Tool naming:

  • Tool name = API operationId

Tool arguments:

  • Path parameters are top-level arguments
  • Query parameters are top-level arguments
  • JSON request body is nested under body
  • Optional accountId maps to X-Account-Id
  • Optional entityId maps to X-Entity-Id

Example shape:

{
  "entityId": "ent_507f1f77bcf86cd799439011",
  "body": {
    "customer": {
      "name": "Acme Inc."
    },
    "items": [
      {
        "name": "Design retainer",
        "quantity": 1,
        "price": 1200
      }
    ]
  }
}

Entity and Account Scoping

Most integrations should use API keys and pass entityId only when the key is allowed to work across multiple entities.

Use:

  • entityId when the action must target a specific legal entity
  • accountId when a user token or account-level context needs an explicit account

If you omit entityId and your token only has access to one entity, Space Invoices auto-selects it. If multiple entities are available, the tool call will fail and ask for explicit entity selection.

In practice:

  • Use an entity API key when the MCP client should always stay scoped to one business
  • Use an account API key when the MCP client needs access to multiple entities under the same account
  • When using an account API key, pass entityId for operations that should target a specific entity

Client Setup

In MCP clients that support remote Streamable HTTP servers:

  1. Create or choose a Space Invoices API key
  2. Add a remote MCP server
  3. Set the URL to https://eu.spaceinvoices.com/mcp
  4. Send Authorization: Bearer ...
  5. Refresh the tool list

This works well with clients such as:

  • Claude Desktop
  • Cursor
  • Claude Code

Client UIs change over time, but the stable pieces are the same:

  • remote MCP / Streamable HTTP transport
  • endpoint URL
  • bearer header

Example Workflows

Examples of prompts that work well:

  • “List my overdue invoices for entity ent_....”
  • “Create a draft invoice for Acme for a monthly platform fee.”
  • “Find customer Jane Doe and show her last three invoices.”
  • “Create a new customer from this company information and then draft an invoice.”
  • “List unpaid invoices and summarize total outstanding by currency.”

Safety Notes

MCP tool calls execute real API operations.

Keep these in mind:

  • Use sandbox keys for testing
  • Use draft-first prompts when creating documents
  • Scope tools with entityId when working across multiple businesses
  • Treat API keys as production credentials

Response Behavior

Tool calls return the same JSON payloads you would get from the REST API, wrapped as MCP tool results.

If the underlying API would return a validation or authorization error, the MCP tool returns that error instead of hiding it behind a generic assistant message.