> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chift.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# Model Context Protocol (MCP)
## Overview
The Chift Model Context Protocol (MCP) defines a set of tools you can use to build AI Agents that can interact with the different integrations offered by Chift and search in our documentation through one MCP server. It exposes the Chift Unified API to any LLM provider supporting the [MCP protocol](https://modelcontextprotocol.io/introduction) like Claude, Cursor or Windsurf.
Chift MCP server can be found [here](https://github.com/chift-oneapi/chift-mcp).
## Getting started
You can use the Chift MCP server in two ways:
1. **[Remote Server (Recommended)](/ai/mcp#remote-server-recommended)** - Connect directly to our hosted MCP server
2. **[Local Installation](/ai/mcp#local-installation)** - Install and run the server locally using the open-source Python package
Choose the option that best fits your needs:
### Remote server (recommended)
The remote server is the easiest way to get started with Chift MCP. No local installation required!
#### Prerequisites
* A [Chift account](https://app.chift.eu) with at least one consumer (organization) that has active integrations
* An MCP-compatible client (e.g., Claude Desktop, Cursor, VS Code, Claude Code, or any AI framework supporting MCP)
#### Authentication
There are two ways to authenticate with the remote MCP server:
The Chift MCP server supports **OAuth 2.0** with **Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))** as the primary authentication method. Just point your MCP client at `https://mcp.chift.eu/mcp` — registration, token exchange, and credential persistence are all handled automatically.
When connecting for the first time, you will be redirected to the Chift platform where you log in, select a consumer, and choose which scopes to grant:
#### Getting an access token
On subsequent connections, saved credentials are reused without re-authenticating.
This authentication method is maintained for backward compatibility. We
recommend using the OAuth 2.0 flow for new integrations.
You can obtain an access token by making a POST request to `https://api.chift.eu/mcp-token`:
```bash theme={null}
curl -X POST 'https://api.chift.eu/mcp-token' \
-H 'Content-Type: application/json' \
-d '{
"clientId": "your_client_id",
"clientSecret": "your_client_secret",
"accountId": "your_account_id",
"consumerId": "your_consumer_id"
}'
```
**Response:**
```json theme={null}
{
"access_token": "your_mcp_access_token",
"token_type": "bearer",
"expires_in": 1800,
"expires_on": 1234567890
}
```
#### Required parameters
Your Chift client ID
Your Chift client secret
Your Chift account ID (UUID format)
Your consumer ID (UUID format)
Optional environment ID (UUID format)
Optional marketplace ID (UUID format)
#### Using with AI frameworks
You can integrate the Chift MCP server with popular AI frameworks to build intelligent applications that interact with Chift's Unified API.
Connect to the Chift MCP server using the Vercel AI SDK:
```typescript theme={null}
import { createMCPClient } from "@ai-sdk/mcp";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
async function getTools() {
const response = await fetch("https://api.chift.eu/mcp-token", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
clientId: "your_client_id",
clientSecret: "your_client_secret",
accountId: "your_account_id",
consumerId: "your_consumer_id",
}),
});
const { access_token } = await response.json();
const mcpClient = createMCPClient({
transport: {
type: "http",
url: "https://mcp.chift.eu/mcp",
headers: {
Authorization: `Bearer ${access_token}`,
},
},
});
return await mcpClient.listTools();
}
// Use with AI SDK
const result = await generateText({
model: openai("gpt-4"),
tools: await getTools(),
prompt: "List all accounting connections for my consumer",
});
```
Connect to the Chift MCP server using Pydantic AI:
```python theme={null}
import httpx
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP
async def get_tools():
async with httpx.AsyncClient() as client:
response = await client.post(
"https://api.chift.eu/mcp-token",
json={
"clientId": "your_client_id",
"clientSecret": "your_client_secret",
"accountId": "your_account_id",
"consumerId": "your_consumer_id",
},
)
data = response.json()
access_token = data["access_token"]
return MCPServerStreamableHTTP(
"https://mcp.chift.eu/mcp",
headers={"Authorization": f"Bearer {access_token}"}
)
async def main():
tools = await get_tools()
agent = Agent("openai:gpt-4", toolsets=[tools])
result = await agent.run("Give me my orders of yesterday")
print(result.output)
if __name__ == "__main__":
import asyncio
asyncio.run(main())
```
Connect to the Chift MCP server using LangChain Python:
```python theme={null}
import httpx
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
async def get_tools():
async with httpx.AsyncClient() as client:
response = await client.post(
"https://api.chift.eu/mcp-token",
json={
"clientId": "your_client_id",
"clientSecret": "your_client_secret",
"accountId": "your_account_id",
"consumerId": "your_consumer_id",
},
)
data = response.json()
access_token = data["access_token"]
client = MultiServerMCPClient({
"chift": {
"url": "https://mcp.chift.eu/mcp",
"transport": "streamable_http",
"headers": {
"Authorization": f"Bearer {access_token}"
}
}
})
tools = await client.get_tools()
return tools
async def main():
tools = await get_tools()
llm = ChatOpenAI(model="gpt-4")
agent = create_agent({
"model": llm,
"tools": tools,
})
# Use the agent
result = agent.invoke({
"messages": [("user", "List all accounting connections")]
})
print(result)
if __name__ == "__main__":
import asyncio
asyncio.run(main())
```
Connect to the Chift MCP server using LangChain TypeScript:
```typescript theme={null}
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { ChatOpenAI } from "@langchain/openai";
import { createAgent } from "langchain/agents";
async function getTools() {
const response = await fetch("https://api.chift.eu/mcp-token", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
clientId: "your_client_id",
clientSecret: "your_client_secret",
accountId: "your_account_id",
consumerId: "your_consumer_id",
}),
});
const { access_token } = await response.json();
const client = new MultiServerMCPClient({
chift: {
transport: "streamable_http",
url: "https://mcp.chift.eu/mcp",
headers: {
Authorization: `Bearer ${access_token}`,
},
},
});
const tools = await client.getTools();
}
async function main() {
const tools = await client.getTools();
const llm = new ChatOpenAI({
model: "gpt-4",
});
const agent = createAgent({
model: llm,
tools: tools,
});
const result = await agent.invoke({
messages: [["user", "List all accounting connections"]],
});
console.log(result);
}
main();
```
The AI framework examples above use the legacy token method for simplicity.
For production applications, we recommend implementing OAuth 2.0.
#### IDE configuration
Add the following to your `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"chift-remote": {
"command": "/path/to/npx",
"args": [
"mcp-remote",
"https://mcp.chift.eu/",
"--transport",
"http-only",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer "
}
}
}
}
```
You will be prompted to log in and authorize access when you first use the MCP tools.
[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=chift\&config=eyJ1cmwiOiJodHRwczovL21jcC5jaGlmdC5ldS9tY3AifQ%3D%3D)
Click install to open Cursor and automatically add the Chift MCP, or add the following to your `~/.cursor/mcp.json` file. To learn more, see the Cursor [documentation](https://docs.cursor.com/context/model-context-protocol).
```json theme={null}
{
"mcpServers": {
"chift": {
"url": "https://mcp.chift.eu/mcp"
}
}
}
```
[Install in VS Code](https://vscode.dev/redirect/mcp/install?name=chift\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.chift.eu%2Fmcp%22%7D)
Click install to open VS Code and automatically add the Chift MCP, or add the following to your `.vscode/mcp.json` file. To learn more, see the VS Code [documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
```json theme={null}
{
"servers": {
"chift": {
"type": "http",
"url": "https://mcp.chift.eu/mcp"
}
}
}
```
Run the following command. To learn more, see the Claude Code [documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#configure-mcp-servers).
```bash theme={null}
claude mcp add --transport http chift https://mcp.chift.eu/mcp
```
All IDEs handle the OAuth flow automatically — you will be prompted to log in and authorize on first use. If you prefer to use a legacy token instead, add an `Authorization: Bearer ` header to the configuration above.
#### Setup steps
1. Choose your preferred IDE from the tabs above
2. Either use the one-click install link or manually add the configuration
3. If using OAuth: you will be prompted to log in and authorize on first use
4. If using legacy tokens: get your token from the `/mcp-token` endpoint first
5. Restart your IDE/application
6. You should see the Chift tools available in the chat interface
The remote server setup is complete! You can now use Chift MCP tools in your
chosen IDE without any local dependencies.
### Local installation
You can also run the MCP server locally in a `stdio` environment using the open-source Python package. Local installation is ideal if you want better AI support during integration of the Chift API. Running the MCP server locally allows you to:
* Choose between limiting the MCP server to a specific consumer or allowing access to all
* Search and reference the entire Chift Documentation directly from your IDE for improved AI context
* Customize your setup for specific workflows
The local MCP server source code can be found [here](https://github.com/chift-oneapi/chift-mcp).
#### Prerequisites
* A Chift account with client credentials (client ID, client secret, account ID, and consumer ID)
* Python 3.11 or higher
* uv package manager
More information about local installation can be found [here](https://github.com/chift-oneapi/chift-mcp?tab=readme-ov-file#prerequisites).
#### Installation steps
1. Install the required dependencies (Python 3.11+ and uv)
2. Install the Chift MCP server package
3. Configure your environment variables
4. Set up your client configuration
#### Using with AI frameworks (local installation)
When running the MCP server locally, you can integrate it with popular AI frameworks using stdio transport. Local installation enables documentation search and provides better control over your setup.
For local installation, use stdio transport:
```typescript theme={null}
import { createMCPClient } from "@ai-sdk/mcp";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
async function getTools() {
const mcpClient = createMCPClient({
command: "uvx",
args: ["chift-mcp-server@latest"],
env: {
CHIFT_CLIENT_SECRET: process.env.CHIFT_CLIENT_SECRET,
CHIFT_CLIENT_ID: process.env.CHIFT_CLIENT_ID,
CHIFT_ACCOUNT_ID: process.env.CHIFT_ACCOUNT_ID,
CHIFT_CONSUMER_ID: process.env.CHIFT_CONSUMER_ID,
CHIFT_SEARCH: "true",
},
});
return await mcpClient.listTools();
}
const result = await generateText({
model: openai("gpt-4"),
tools: await getTools(),
prompt: "Search the documentation for webhook authentication",
});
```
For local installation with stdio transport:
```python theme={null}
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
async def main():
tools = MCPServerStdio(
command="uvx",
args=["chift-mcp-server@latest"],
env={
"CHIFT_CLIENT_SECRET": "your_client_secret",
"CHIFT_CLIENT_ID": "your_client_id",
"CHIFT_ACCOUNT_ID": "your_account_id",
"CHIFT_CONSUMER_ID": "your_consumer_id",
"CHIFT_SEARCH": "true",
}
)
agent = Agent("openai:gpt-4", toolsets=[tools])
result = await agent.run("Search documentation for webhook setup")
print(result.output)
if __name__ == "__main__":
import asyncio
asyncio.run(main())
```
For local installation with stdio transport:
```python theme={null}
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
import os
async def get_tools():
client = MultiServerMCPClient({
"chift": {
"command": "uvx",
"args": ["chift-mcp-server@latest"],
"transport": "stdio",
"env": {
"CHIFT_CLIENT_SECRET": os.getenv("CHIFT_CLIENT_SECRET"),
"CHIFT_CLIENT_ID": os.getenv("CHIFT_CLIENT_ID"),
"CHIFT_ACCOUNT_ID": os.getenv("CHIFT_ACCOUNT_ID"),
"CHIFT_CONSUMER_ID": os.getenv("CHIFT_CONSUMER_ID"),
"CHIFT_SEARCH": "true",
}
}
})
tools = await client.get_tools()
return tools
async def main():
tools = await get_tools()
llm = ChatOpenAI(model="gpt-4")
agent = create_agent({
"model": llm,
"tools": tools,
})
result = agent.invoke({
"messages": [("user", "Search documentation for webhook setup")]
})
print(result)
if __name__ == "__main__":
import asyncio
asyncio.run(main())
```
For local installation with stdio transport:
```typescript theme={null}
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { ChatOpenAI } from "@langchain/openai";
import { createAgent } from "langchain/agents";
async function getTools() {
const client = new MultiServerMCPClient({
chift: {
transport: "stdio",
command: "uvx",
args: ["chift-mcp-server@latest"],
env: {
CHIFT_CLIENT_SECRET: process.env.CHIFT_CLIENT_SECRET!,
CHIFT_CLIENT_ID: process.env.CHIFT_CLIENT_ID!,
CHIFT_ACCOUNT_ID: process.env.CHIFT_ACCOUNT_ID!,
CHIFT_CONSUMER_ID: process.env.CHIFT_CONSUMER_ID!,
CHIFT_SEARCH: "true",
},
},
});
const tools = await client.getTools();
return tools;
}
async function main() {
const tools = await getTools();
const llm = new ChatOpenAI({
model: "gpt-4",
});
const agent = createAgent({
model: llm,
tools: tools,
});
const result = await agent.invoke({
messages: [["user", "Search documentation for webhook authentication"]],
});
console.log(result);
}
main();
```
For local installations, you can enable documentation search by setting
`CHIFT_SEARCH=true` in your environment variables. This allows the MCP server
to search and reference the entire Chift Documentation directly from your IDE.
#### IDE configuration
This is an example configuration for Claude Desktop when using local installation:
```json theme={null}
{
"mcpServers": {
"chift": {
"command": "/path/to/uvx",
"args": ["chift-mcp-server@latest"],
"env": {
"CHIFT_CLIENT_SECRET": "your_client_secret",
"CHIFT_CLIENT_ID": "your_client_id",
"CHIFT_ACCOUNT_ID": "your_account_id",
"CHIFT_CONSUMER_ID": "your_consumer_id", // Optional
"CHIFT_SEARCH": true // Optional, defaults to false
}
}
}
}
```
For local installation with Cursor, add the following to your `~/.cursor/mcp.json` file:
```json theme={null}
{
"mcpServers": {
"chift": {
"command": "/path/to/uvx",
"args": ["chift-mcp-server@latest"],
"env": {
"CHIFT_CLIENT_SECRET": "your_client_secret",
"CHIFT_CLIENT_ID": "your_client_id",
"CHIFT_ACCOUNT_ID": "your_account_id",
"CHIFT_CONSUMER_ID": "your_consumer_id", // Optional
"CHIFT_SEARCH": true // Optional, defaults to false
}
}
}
}
```
For local installation with VS Code, add the following to your `.vscode/mcp.json` file in your workspace:
```json theme={null}
{
"servers": {
"chift": {
"type": "stdio",
"command": "/path/to/uvx",
"args": ["chift-mcp-server@latest"],
"env": {
"CHIFT_CLIENT_SECRET": "your_client_secret",
"CHIFT_CLIENT_ID": "your_client_id",
"CHIFT_ACCOUNT_ID": "your_account_id",
"CHIFT_CONSUMER_ID": "your_consumer_id", // Optional
"CHIFT_SEARCH": true // Optional, defaults to false
}
}
}
}
```
For local installation with Claude Code, first ensure you have the MCP server installed locally, then run:
```bash theme={null}
claude mcp add --transport stdio chift /path/to/uvx chift-mcp-server@latest
```
Then set your environment variables:
```bash theme={null}
export CHIFT_CLIENT_SECRET="your_client_secret"
export CHIFT_CLIENT_ID="your_client_id"
export CHIFT_ACCOUNT_ID="your_account_id"
export CHIFT_CONSUMER_ID="your_consumer_id" // Optional
export CHIFT_SEARCH=true // Optional, defaults to false
```
#### Setup steps
1. Install Python 3.11+ and uv on your system
2. Install the Chift MCP server: `uvx chift-mcp-server@latest`
3. Set up your environment variables (see below)
4. Choose your preferred IDE from the tabs above and add the configuration
5. Replace the credential placeholders with your actual values
6. Restart your IDE/application
7. You should see the Chift tools available in the chat interface
#### Environment variables for local installation
The following environment variables are required for local installation:
```bash theme={null}
CHIFT_CLIENT_SECRET=your_client_secret
CHIFT_CLIENT_ID=your_client_id
CHIFT_ACCOUNT_ID=your_account_id
CHIFT_CONSUMER_ID=your_consumer_id # Optional
CHIFT_SEARCH=true # Optional, defaults to false
```
Local installation is complete! You now have full control over your MCP server
instance and can use Chift MCP tools in your chosen IDE.
## Other LLM providers
The Chift MCP server works with any LLM provider that supports the MCP protocol, not just Claude Desktop.
We have elaborated on several examples (PydanticAI, Copilot, ...) [here](https://github.com/chift-oneapi/chift-ai-toolkit).
## Available tools
The Chift MCP Server dynamically generates tools based on the Chift OpenAPI specification. These tools provide access to various Chift API endpoints and include operations for:
* Retrieving financial data
* Managing your financial connections
* Creating new financial records (invoices, payments, etc.)
* Updating existing records
* And much more...
All our endpoints documented in our [API reference](/api-reference) can be accessed through the Chift MCP server. The tools available to you depend on the **scopes** granted during authentication — you will only see tools for the verticals and operations you have been authorized for.
Because the tools mirror the Unified API one-to-one, an agent can both read and write across your integrations. For example, asking an assistant to create an invoice walks through the same steps you would: it locates the customer, checks the VAT and revenue coding already used in the ledger, and posts a consistent invoice.
## Advanced configuration
### DataLayer integration
If the [DataLayer](/developer-guides/datalayer/overview) is active on the consumer you authorized, the MCP server automatically uses it as the source of truth for read operations. This means your AI agent's queries are served from Chift's synced data store rather than hitting the source accounting system live on every request, resulting in faster and more consistent responses.
You do not need to configure anything for this to work. When the consumer has a datalayer sync enabled, the MCP server routes all requests through the data layer.
The data layer is ideal for AI agents that need to compute over large amounts
of financial data. Learn more about how it works in the [DataLayer
overview](/developer-guides/datalayer/overview).
### Function configuration (local installation only)
For local installations, you can customize which operations are available for each domain. By default, all operations are enabled for all domains:
```json theme={null}
{
"accounting": ["get", "create", "update", "add"],
"commerce": ["get", "create", "update", "add"],
"invoicing": ["get", "create", "update", "add"],
"payment": ["get", "create", "update", "add"],
"pms": ["get", "create", "update", "add"],
"pos": ["get", "create", "update", "add"]
}
```
This can be customized using the `CHIFT_FUNCTION_CONFIG` environment variable. More details can be found [here](https://github.com/chift-oneapi/chift-mcp?tab=readme-ov-file#%EF%B8%8F-function-configuration).
Function configuration is only available for local installations. The remote
server uses scope-based access control to determine which operations are
available.