MCP Server

The fiskaly-docs MCP server gives AI coding assistants direct access to fiskaly documentation, OpenAPI specifications, product metadata, and error codes — without web scraping or manual lookups.

It implements the Model Context Protocol (MCP) and exposes 9 tools that any MCP-compatible client can call.

Available tools

Documentation tools

Search documentation pages by keyword. Returns matching page titles, paths, and relevant 500-character snippets.

Parameters:

• query (required) — search keyword (substring match on title and body)
• product (optional) — filter by product name, e.g. SIGN DE, SIGN FR
• country (optional) — filter by country code, e.g. DE, FR, IT

Read a full documentation page by path. Supports partial and suffix matching. Returns the complete page body and related sibling pages.

Parameters:

• path (required) — page path or suffix, e.g. getting-started/quickstart, quickstart

Get metadata for a fiskaly product: description, country, API architecture, base URLs, docs links, and related pages.

Parameters:

• product (required) — product ID (e.g. sign-de, sign-fr) or product name (e.g. SIGN DE, DSFinV-K)

Get fiskaly API error codes with HTTP status, description, and fix guidance. Optionally filter by product.

Parameters:

• product (optional) — filter by product ID (e.g. sign-de, sign-fr). Omit to get all error codes.

API exploration tools

Get the OpenAPI specification for a fiskaly product. Use format="summary" for an overview of endpoints and schema names instead of the full spec.

Parameters:

• product (required) — product ID: sign-de, sign-at, sign-fr, sign-it, sign-es, dsfinvk, ereceipt, management, obono
• format (optional) — full (default) or summary (info + endpoint list + schema names)

List all API endpoints for a product, grouped by tag. Shows method, path, operationId, and summary.

Parameters:

• product (required) — product ID
• tag (optional) — filter by tag name (case-insensitive partial match)

Get detailed information about a specific endpoint: parameters, request body, response schemas, and security.

Parameters:

• product (required) — product ID
• path (optional) — API path to match (partial match)
• method (optional) — HTTP method (GET, POST, PUT, etc.)
• operationId (optional) — operation ID (partial, case-insensitive)

Look up an OpenAPI schema by name with $ref expansion (2 levels deep, cycle-safe). Use list=true to see all available schemas.

Parameters:

• product (required) — product ID
• schema (optional) — schema name (partial, case-insensitive match)
• list (optional) — set to true to list all schema names

Integration tools

Get a Step-by-Step Integration guide for a product. Composes environment info, authentication flow, quickstart steps from docs, key endpoints from the spec, and documentation links.

Parameters:

• product (required) — product ID or name (e.g. sign-de, SIGN FR)

Setup

💡Tip

All setup methods below run the server via npx. On first launch, npx downloads the package, which can exceed your MCP client’s startup timeout and surface as a one-time failed to connect / -32000 error. Pre-warm the cache by running npx -y @fiskaly/docs-mcp once in a terminal (wait for it to start, then press Ctrl+C), then add the server to your client.

If you still see a connection error, see Troubleshooting. Make sure Node.js is installed and on your client’s PATH — verify with node --version.

Claude Code

Add the fiskaly-docs MCP server to your project:

claude mcp add fiskaly-docs -- npx @fiskaly/docs-mcp

Or add it to your project’s .mcp.json:

{
  "mcpServers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["@fiskaly/docs-mcp"]
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["@fiskaly/docs-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["@fiskaly/docs-mcp"]
    }
  }
}

VS Code (GitHub Copilot)

Add to your project’s .vscode/mcp.json:

{
  "servers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["@fiskaly/docs-mcp"]
    }
  }
}

JetBrains IDEs

Go to Settings > Tools > AI Assistant > Model Context Protocol and add a new server with:

• Command: npx
• Arguments: @fiskaly/docs-mcp

Generic MCP clients

The server communicates over stdio using the MCP protocol. Start it with:

npx @fiskaly/docs-mcp

It requires Node.js 24+.

Example usage

Read a full documentation page

Tool: get_doc_page
Input: { "path": "getting-started/quickstart" }

Returns the complete page body with sibling page links — ideal for reading integration guides end-to-end.

Browse API endpoints

Tool: list_endpoints
Input: { "product": "sign-de", "tag": "Transaction" }

Returns all transaction-related endpoints grouped by tag, with method, path, operationId, and summary.

Look up a specific endpoint

Tool: get_endpoint
Input: { "product": "sign-de", "operationId": "upsertTransaction" }

Returns focused detail: parameters, request body schema (resolved), response schemas, and security requirements.

Get an integration guide

Tool: get_integration_guide
Input: { "product": "sign-fr" }

Returns a composed guide with environment URLs, authentication flow, quickstart content, key endpoints from the spec, and links to relevant documentation pages.

Resolve a schema

Tool: resolve_schema
Input: { "product": "sign-de", "schema": "Transaction" }

Returns the resolved schema with $ref expanded 2 levels deep. Use list=true to see all available schema names first.

Get a spec summary

Tool: get_openapi_spec
Input: { "product": "sign-de", "format": "summary" }

Returns API info, a list of all endpoints, and schema names — without the full 5000+ line spec.

Searching documentation

Tool: search_docs
Input: { "query": "transaction", "product": "SIGN DE" }

Returns matching pages with titles, paths, and 500-character content snippets relevant to SIGN DE transactions.

Looking up product metadata

Tool: get_product_info
Input: { "product": "sign-de" }

Returns structured metadata:

• Product name, description, and country
• API architecture (specialized or unified)
• Base URLs for TEST and LIVE environments
• Spec URL, docs URL, and related pages

Looking up error codes

Tool: get_error_codes
Input: { "product": "sign-de" }

Returns all error codes for SIGN DE with HTTP status codes, descriptions, and resolution guidance.

Troubleshooting

failed to connect to MCP server / error code -32000? This JSON-RPC error means your MCP client could not spawn the server or complete the handshake over stdio. In order of likelihood:

1. npx cold-start timeout (most common). On first run, npx downloads @fiskaly/docs-mcp, which often takes longer than your client’s startup timeout. Run npx -y @fiskaly/docs-mcp once in a terminal to pre-warm the cache, then restart your client.
2. npx or node not found in the client’s environment. MCP clients frequently launch with a minimal PATH that doesn’t include your Node install (common with nvm, fnm, or Homebrew). If which npx works in your terminal but the server still won’t start, point the client at an absolute path — set command to the full path from which node and pass the package as an argument, or use the absolute path to npx.
3. Stale or corrupted npx cache. If the server previously worked and suddenly fails, clear the cache and let it re-download: rm -rf "$(npm config get cache)/_npx", then restart your client.

Make sure Node.js is installed and on the PATH your client uses. Run node --version to confirm — and note that some clients use a different shell or Node than your terminal, so verify the environment your client actually launches.

No results from search_docs? Try a broader search term. The search uses substring matching on titles and body text — shorter keywords return more results.

get_openapi_spec returning an error? Not all products have an OpenAPI spec. Use get_product_info to check if a product has a specFile.

Alternative: HTTP endpoints

If you prefer HTTP over MCP, the same data is available as machine-readable endpoints:

• Search docs — fetch and search /llms-full.txt
• OpenAPI specs — fetch /specs/{product}.json or .yaml directly
• Product info — fetch /products.json
• Error codes — use get_error_codes via MCP, or check the Error Codes reference