> ## 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.

# Local MCP server

> Run the open-source Chift MCP server locally to explore and configure Chift across your consumers

## Overview

The local MCP server is an open-source Python package you run on your own machine over `stdio`. You authenticate once with your Chift API credentials, and unlike the [remote server](/ai/mcp/remote) it can work across **all of your consumers** rather than a single one.

It is built for **builders**: if you have a Chift account with several consumers and you want an assistant that helps you configure Chift and explore the Unified API across them, the local server is the right tool. It also offers an optional [documentation search](#documentation-search) tool that brings the entire Chift documentation into your coding assistant's context.

The source code is available on [GitHub](https://github.com/chift-oneapi/chift-mcp).

### Prerequisites

* A Chift account with API credentials (client ID, client secret, and account ID).
* Python 3.11 or higher.
* The [uv](https://docs.astral.sh/uv/) package manager.

More detail on prerequisites is available in the [project README](https://github.com/chift-oneapi/chift-mcp?tab=readme-ov-file#prerequisites).

## Installation

The server runs with `uvx`, which fetches and launches the package in one step:

```bash theme={null}
uvx chift-mcp-server@latest
```

You normally do not run this by hand. Your MCP client launches it for you using the configuration in [Connecting your client](#connecting-your-client). Set your credentials as environment variables first (see [Configuration](#configuration)).

## Configuration

The server reads its configuration from environment variables (prefixed with `CHIFT_`), which you can set in your MCP client configuration or a local `.env` file.

| Variable                | Description                                                                                                | Required |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- | -------- |
| `CHIFT_CLIENT_ID`       | Your Chift client ID                                                                                       | Yes      |
| `CHIFT_CLIENT_SECRET`   | Your Chift client secret                                                                                   | Yes      |
| `CHIFT_ACCOUNT_ID`      | Your Chift account ID                                                                                      | Yes      |
| `CHIFT_CONSUMER_ID`     | Restrict the server to a single consumer. Leave unset to work across all of your consumers                 | No       |
| `CHIFT_SEARCH`          | Set to `true` to enable the [documentation search](#documentation-search) tool (defaults to `false`)       | No       |
| `CHIFT_FUNCTION_CONFIG` | Restrict which operations are available per domain (see [Function configuration](#function-configuration)) | No       |

<Tip>
  Leaving `CHIFT_CONSUMER_ID` unset is what makes the local server useful to builders: the assistant can discover and work across every consumer on your account. Set it when you want to pin a session to one consumer.
</Tip>

## Connecting your client

### IDE configuration

<Tabs>
  <Tab title="Claude Desktop">
    Add the following to your `claude_desktop_config.json`:

    ```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
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="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
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add the following to your `.vscode/mcp.json` file:

    ```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
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Add the server, then set your environment variables:

    ```bash theme={null}
    claude mcp add --transport stdio chift /path/to/uvx chift-mcp-server@latest
    ```

    ```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
    ```
  </Tab>
</Tabs>

### Using with AI frameworks

When running locally you integrate the server over `stdio` transport.

<Tabs>
  <Tab title="AI SDK (Vercel)">
    ```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",
    });
    ```
  </Tab>

  <Tab title="Pydantic AI">
    ```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())
    ```
  </Tab>

  <Tab title="LangChain Python">
    ```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())
    ```
  </Tab>

  <Tab title="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 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",
          },
        },
      });

      return await client.getTools();
    }

    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();
    ```
  </Tab>
</Tabs>

## Function configuration

By default, all operations are enabled for every domain:

```json theme={null}
{
  "accounting": ["get", "create", "update", "add"],
  "banking": ["get", "create", "update", "add"],
  "ecommerce": ["get", "create", "update", "add"],
  "invoicing": ["get", "create", "update", "add"],
  "payment": ["get", "create", "update", "add"],
  "pms": ["get", "create", "update", "add"],
  "pos": ["get", "create", "update", "add"]
}
```

Set the `CHIFT_FUNCTION_CONFIG` environment variable to restrict which operations are exposed per domain, for example to give an assistant read-only access. More detail is available in the [project README](https://github.com/chift-oneapi/chift-mcp?tab=readme-ov-file#%EF%B8%8F-function-configuration).

<Note>
  Function configuration is specific to the local server. The [remote server](/ai/mcp/remote) uses OAuth scopes to control which operations are available.
</Note>

## Documentation search

The local server can expose a `SearchChift` tool that searches the entire Chift documentation like a vector database: pass a query and retrieve the documentation passages that match semantically. It brings Chift documentation directly into your coding assistant's context, which helps it integrate Chift faster.

The tool is off by default. Enable it by setting:

```bash theme={null}
CHIFT_SEARCH=true
```

```javascript theme={null}
// Search documentation via MCP
const result = await mcp.call_tool('SearchChift', {
  query: 'How to authenticate webhook requests?'
});
```