MCP Server

The flinkey MCP Server exposes flinkey API operations as callable tools for AI coding agents and LLM-based assistants. It implements the Model Context Protocol and can be used from any MCP-compatible client — including Cursor, Claude Desktop, Windsurf, Cline and custom agent setups.

Endpoint

https://flinkey.mcp.witte.digital

The server uses the Streamable HTTP transport (the current MCP standard). No session management or SSE subscription is needed — each request is self-contained.

Configuration

Add the server to your agent’s MCP settings:

{
  "mcpServers": {
    "flinkey": {
      "url": "https://flinkey.mcp.witte.digital",
      "headers": {
        "X-Flinkey-API-Key": "{{flinkeyApiKey}}",
        "X-Flinkey-Username": "{{FLINKEY_API_MANAGER_USERNAME}}",
        "X-Flinkey-Password": "{{FLINKEY_API_MANAGER_PASSWORD}}",
        "X-Flinkey-Customer-ID": "{{FLINKEY_CUSTOMER_ID}}",
        "X-Flinkey-Env": "uat"
      }
    }
  }
}

Required headers

Header	Description	Required
`X-Flinkey-API-Key`	flinkey subscription key	Yes
`X-Flinkey-Username`	API Manager username	Yes
`X-Flinkey-Password`	API Manager password	Yes
`X-Flinkey-Customer-ID`	Customer context ID	No
`X-Flinkey-Env`	Environment: `uat` or `prod`	No (default: `uat`)

If X-Flinkey-Customer-ID is omitted, use the get-customers tool to resolve it.

Available tools

Guide

Tool	Description
`get-guide`	Returns the integration model, recommended workflows, async/webhook behavior and tool reference

Customers

Tool	Description
`get-customers`	Retrieve all customer contexts reachable by the API Manager

Cars

Tool	Description
`list-cars`	List all vehicles in the customer context
`get-car`	Retrieve a single car by ID
`create-car`	Create a new car
`update-car`	Update car fields via JSON Patch
`delete-car`	Delete a car

Users

Tool	Description
`list-users`	List users in the customer context
`get-user`	Retrieve a single user by ID
`create-user`	Create a new user (Anonymous or Normal)

Assignments

Tool	Description
`create-assignment`	Create a vehicle access assignment (async)
`get-assignment`	Retrieve an assignment by ID
`update-assignment`	Update an assignment via patch operations (async)
`delete-assignment`	Delete an assignment (async)
`list-car-assignments`	List all assignments for a car
`list-user-assignments`	List all assignments for a user

Events

Tool	Description
`get-event`	Retrieve a single event by ID
`list-car-events`	List events for a car

Recommended workflow

Load context

Call get-guide to understand the integration model, object relationships and async behavior.
Resolve customer

Call get-customers to identify the correct Customer-ID for subsequent operations.
Perform operations

Use car, user, assignment and event tools as needed. Remember that assignment writes are asynchronous.

Error handling

Missing credentials

If required headers are missing, the server returns HTTP 401 with a descriptive message:

{
  "error": "Missing or invalid credential headers: apiManagerUsername, apiManagerPassword. Required: X-Flinkey-API-Key, X-Flinkey-Username, X-Flinkey-Password"
}

API errors

If the flinkey API returns an error (e.g. invalid credentials, resource not found), the tool response contains an error message with the HTTP status and details.

Environment

Control the target environment via the X-Flinkey-Env header:

Value	API Target
`uat` (default)	`https://api-uat.flinkey.de/v3`
`prod`	`https://api.flinkey.de/v3`

If the header is omitted, the server defaults to UAT.

Self-hosting

If you run the MCP server yourself, the server-side FLINKEY_ENV variable sets the default when no X-Flinkey-Env header is sent:

# Default to UAT (clients can still override via header)
FLINKEY_ENV=uat node dist/index.js --remote 3000

# Default to PROD
FLINKEY_ENV=prod node dist/index.js --remote 3000

Example session

A typical agent session might look like:

Agent: [calls get-guide]
→ Receives integration model, async behavior, tool overview

Agent: [calls get-customers]
→ Receives: [{ id: 357, name: "Partner Corp" }]

Agent: [calls list-cars with customerId: "357"]
→ Receives list of vehicles with IDs, names, license plates

Agent: [calls create-assignment with carId, userId, start, end]
→ Receives: "Assignment creation accepted. Final result arrives via webhook."