MCP Integration
Connect Haufe Copilot tools to AI agents and workflows via the Model Context Protocol (MCP).
The MCP lets any MCP-compatible AI agent or workflow call Haufe Copilot tools directly — without building a REST integration. Once configured, your agent can invoke specialized copilots (Tax, HR, Sustainability, Real Estate, ...) as native tools.
Prerequisites
Before connecting an MCP client, you need:
| Requirement | Where to get it |
|---|---|
| API key | Developer Portal |
| License ID(s) | Provided by your Haufe contact person |
| MCP-compatible client | Claude Desktop, Claude Code, Python mcp SDK, or any MCP client |
Available Tools
The MCP server exposes one tool per copilot. Each tool accepts a single user_message argument and returns a
JSON-encoded assistant response.
| Tool name | Domain | License header required |
|---|---|---|
haufe_copilot_tax_tool | German tax law (income tax, VAT, corporate tax, payroll tax, trade tax) | license-id-tax |
haufe_copilot_hr_tool | German employment & HR law (contracts, dismissal, works council) | license-id-hr |
haufe_copilot_sustainability_tool | ESRS standards, CSRD directive, ESG compliance | license-id-sustainability |
haufe_copilot_real_estate_tool | German real estate law (tenancy, WEG, landlord/tenant rights) | license-id-re |
Authentication
Every MCP request requires two parameters of credentials passed as HTTP headers:
api-key— your API key, used to identify your tenant.- License header — one header per copilot you want to use (e.g.
license-id-tax: <LICENSE_ID>). You only need to include headers for the tools you intend to call.
License IDs are validated per tool call. Calling a tool without the corresponding license header will result in an authentication error.
Configuration
The MCP server is available at https://api.haufe.ai/agents/v1/mcp and uses Streamable HTTP transport.
Claude Code
Create or update .mcp.json in your project root, or ~/.claude/mcp.json for a global configuration:
{
"mcpServers": {
"haufe-copilot": {
"type": "http",
"url": "https://api.haufe.ai/agents/v1/mcp",
"headers": {
"api-key": "<YOUR_API_KEY>",
"license-id-tax": "<YOUR_TAX_LICENSE_ID>"
}
}
}
}After saving, restart Claude Code. The copilot tools will appear in the tool list.
Python MCP SDK
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
async with streamablehttp_client(
"https://api.haufe.ai/agents/v1/mcp",
headers={
"api-key": "<YOUR_API_KEY>",
"license-id-tax": "<YOUR_TAX_LICENSE_ID>",
},
) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(
"haufe_copilot_tax_tool",
{"user_message": "Was sind die Fristen für die Steuererklärung?"},
)
print(result.content[0].text)
asyncio.run(main())Tool Response Format
Each tool returns a JSON string. Parse it to access the structured response:
import json
raw = result.content[0].text
response = json.loads(raw)
print(response["content"]) # main answer text
print(response["sources"]) # list of cited sourcesThe response schema matches the AssistantMessage returned by the Chat Completions endpoint.