> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/getting-started/appmixer-mcp-server.md).

# Appmixer MCP Server

Connect your Appmixer tenant to Claude, Cursor, VS Code and other MCP clients, so an AI assistant can run, monitor and build your automation flows.

The Appmixer MCP server exposes your Appmixer tenant to any client that speaks the [Model Context Protocol](https://modelcontextprotocol.io): Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and others. Once connected, you can ask an AI assistant to list and troubleshoot your flows, trigger them, and build new automations from a plain-language brief.

{% hint style="info" %}
This page is about **Appmixer acting as an MCP server** for external AI clients. For the opposite direction — wrapping a third-party MCP server as an Appmixer connector so the AI Agent component can use it — see [MCP Servers](https://docs.appmixer.com/building-connectors/mcp-servers.md).
{% endhint %}

***

### What you can do with it

* **Operate flows** — list them, read their configuration and logs, start and stop them, trigger webhook components, send app events.
* **Build flows** — the server ships a flow authoring guide and exposes the connector catalogue, so an assistant can assemble a flow, validate it server-side, check its variable references and dry-run a component before the flow ever runs.
* **Work with the data around your flows** — read and seed data stores, snapshot a flow before an edit and roll it back, clone a flow, and inspect the messages your flows failed on so a broken run can be fixed and replayed.
* **Reach your own tools** — any running flow that contains an **MCP Gateway** component publishes the tools connected to it, so your assistant can call automations you built yourself.

***

### Prerequisites

* An Appmixer tenant and a user account on it.
* An Appmixer access token — see [Authentication](https://docs.appmixer.com/api/authentication.md) for how to obtain one.
* Node.js 20 or newer, unless you install the Claude Desktop bundle or run the server in Docker.

{% hint style="warning" %}
The server acts as the user whose credentials it holds. Use a dedicated, non-admin Appmixer user for AI access so its reach stays limited, and never share one token between people.
{% endhint %}

***

### Install

#### Claude Code

```bash
claude mcp add appmixer \
  -e APPMIXER_BASE_URL="https://api.YOUR_TENANT.appmixer.cloud" \
  -e APPMIXER_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" \
  -- npx appmixer-mcp
```

#### Cursor, VS Code, Windsurf and other clients

Add the server to the client's MCP configuration:

```json
{
  "mcpServers": {
    "appmixer": {
      "command": "npx",
      "args": ["appmixer-mcp"],
      "env": {
        "APPMIXER_BASE_URL": "https://api.YOUR_TENANT.appmixer.cloud",
        "APPMIXER_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
      }
    }
  }
}
```

#### Claude Desktop

Download the `.mcpb` bundle from the [releases page](https://github.com/Appmixer-ai/appmixer-mcp/releases) and double-click it. Claude Desktop asks for your tenant URL and token during installation and stores the token in your operating system's keychain. The bundle contains the server and its dependencies and runs on the Node runtime built into Claude Desktop, so you do not need to install Node.js yourself.

#### Self-hosted remote server

The same server also runs as a remote HTTP endpoint that several people can share, each authenticating with their own Appmixer token:

```bash
git clone https://github.com/Appmixer-ai/appmixer-mcp.git
cd appmixer-mcp
docker build -t appmixer-mcp .
docker run -p 3000:3000 \
  -e APPMIXER_BASE_URL="https://api.YOUR_TENANT.appmixer.cloud" \
  -e MCP_AUTH_MODE=bearer \
  appmixer-mcp
```

Clients then connect to `https://your-host/mcp` and send their token in the `Authorization: Bearer` header. Terminate TLS in a reverse proxy in front of the container.

{% hint style="warning" %}
Custom connectors on claude.ai cannot use this endpoint. They authenticate through OAuth and cannot send a bearer header, so the remote server is for clients that can — Claude Code, Cursor, VS Code and the like. Claude Desktop connects through the bundle above instead.
{% endhint %}

***

### Configuration

| **Variable**            | **Description**                                                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `APPMIXER_BASE_URL`     | **Required.** Your tenant's API URL, for example `https://api.YOUR_TENANT.appmixer.cloud`.                                    |
| `APPMIXER_ACCESS_TOKEN` | Appmixer access token. The recommended way to authenticate.                                                                   |
| `APPMIXER_USERNAME`     | Appmixer username. Needed only without a token, or so the server can renew an expired token on its own.                       |
| `APPMIXER_PASSWORD`     | Appmixer password, used together with the username.                                                                           |
| `TOOLS`                 | Comma-separated tool groups. Defaults to `api,mcpgateway`; set it to `api` to leave out tools published by MCP Gateway flows. |

Access tokens expire after the period configured in your tenant's `GRIDD_JWT_TOKEN_EXP` setting (30 days by default). If you also provide the username and password, the server signs in again automatically when the token expires.

A self-hosted remote server takes a few more variables: `MCP_AUTH_MODE` (`env` or `bearer`), `MCP_HTTP_PORT` and `MCP_HTTP_HOST`, `MCP_ALLOWED_ORIGINS` (the Origin allowlist for browser clients), `MCP_SESSION_IDLE_TIMEOUT`, and — when the endpoint is publicly reachable — `MCP_MAX_SESSIONS` and `MCP_RATE_LIMIT_PER_MINUTE`, which cap how many sessions may run at once and how fast one client may open new ones.

***

### Available tools

**Working with existing flows**

| **Tool**                                 | **What it does**                                                                                          |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `list_flows`, `get_flow`                 | Find flows and read their components, configuration and descriptor.                                       |
| `get_flow_status`, `get_flow_logs`       | Check whether a flow runs and read its execution logs.                                                    |
| `start_flow`, `stop_flow`, `delete_flow` | Control a flow's lifecycle.                                                                               |
| `trigger_component`                      | Send a request to a flow's webhook trigger.                                                               |
| `read_component_trigger`                 | The same for triggers that listen on GET.                                                                 |
| `send_app_event`                         | Fire an [app event](https://docs.appmixer.com/getting-started/use-app-events.md) into your running flows. |

**Building flows**

| **Tool**                                       | **What it does**                                                                                   |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `get_flow_authoring_guide`                     | The flow descriptor format, wiring rules and common mistakes.                                      |
| `list_apps`, `get_components`, `list_accounts` | The connector catalogue: components, their ports and fields, and accounts.                         |
| `create_flow`, `update_flow`, `validate_flow`  | Create or change a flow and validate it server-side.                                               |
| `get_flow_variables`                           | The exact variable paths a component can reference.                                                |
| `test_flow`                                    | Dry-run a component with sample data without starting the flow.                                    |
| `get_component_options`                        | Resolve pickers that load their choices at runtime — a Slack channel list, a spreadsheet's sheets. |
| `get_trigger_url`                              | The public webhook URL of a trigger component, for chaining flows or calling one from outside.     |
| `get_flow_accounts`, `assign_account`          | See which components need a connected account and bind one to them.                                |

**Data, versions and failures**

| **Tool**                                                            | **What it does**                                                                  |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `list_stores`, `create_store`                                       | The data stores your flows read and write through `appmixer.utils.storage`.       |
| `get_store_records`, `set_store_record`, `delete_store_record`      | Read, seed and clean up the records in a store.                                   |
| `list_flow_versions`, `create_flow_version`, `restore_flow_version` | Snapshot a flow before a risky edit and roll it back if the edit goes wrong.      |
| `clone_flow`                                                        | Copy a flow, optionally carrying its connected accounts over.                     |
| `list_modifiers`                                                    | Your tenant's catalogue of `g_*` modifier functions used in flow transformations. |
| `list_unprocessed_messages`, `get_unprocessed_message`              | The messages your flows failed on, with the error and the input that broke.       |
| `retry_unprocessed_message`, `delete_unprocessed_message`           | Replay a failed message once the flow is fixed, or discard it.                    |

{% hint style="info" %}
By default a component that fails parks its message in **Unprocessed Messages** instead of stopping the flow, so a failure is easy to miss. When a flow looks like it ran but produced nothing, ask your assistant to check `list_unprocessed_messages`.
{% endhint %}

***

### Building a flow with an AI assistant

Describe what you want in plain language, for example:

> Build a flow that runs every morning at 8:00, fetches new rows from my Google Sheet and sends me a summary by email. Validate it, but do not start it.

The assistant reads the authoring guide, looks up the components and their fields, creates the flow, and fixes whatever validation reports before handing it back to you. Ask it to run `test_flow` to see real output from a single component, then open the flow in the Designer to review it and start it yourself.

{% hint style="info" %}
Components of third-party services need a connected account. Connect accounts in Appmixer first, then ask the assistant to bind them — it cannot complete an OAuth sign-in on your behalf.
{% endhint %}

***

### Tools published by your own flows

Any running flow that contains the **MCP Gateway** component from the **MCP Tools** category publishes the tools wired to it, so your assistant can call the automations you built. Starting or stopping such a flow adds or removes those tools while the client stays connected.

This requires the `appmixer.ai.mcptools` module on your tenant; see [Install and Update Connectors](https://docs.appmixer.com/getting-started/modules.md). Without it, the flow tools simply do not appear and everything else keeps working.

For the equivalent inside Appmixer — giving tools to an AI Agent that runs in a flow — see [Build and Run an AI agent](https://docs.appmixer.com/getting-started/build-and-run-an-ai-agent.md).

***

### Troubleshooting

| **Symptom**                                  | **What to check**                                                                                                   |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| No Appmixer tools in the client              | The client's MCP server list and its logs; most failures are a mistyped `APPMIXER_BASE_URL`.                        |
| Tools answer with a 401                      | The token expired or belongs to another tenant. Issue a new one, or add the username and password for auto-renewal. |
| A tool answers with 403                      | The user lacks permission for that operation. Check the account's role and ACL rules.                               |
| MCP Gateway tools are missing                | The `appmixer.ai.mcptools` module is not installed, or no flow with an MCP Gateway component is running.            |
| The assistant keeps fixing validation errors | Ask it to call `get_flow_variables` before writing transformations, so it uses real variable paths.                 |
| A flow runs but produces nothing             | `list_unprocessed_messages` — failed messages are parked there, with the error and the input that caused it.        |

***

### Next steps

* [Access Appmixer REST API](https://docs.appmixer.com/getting-started/api.md) — the API behind these tools.
* [Build and Run an AI agent](https://docs.appmixer.com/getting-started/build-and-run-an-ai-agent.md) — AI agents that run inside your flows.
* [MCP Servers](https://docs.appmixer.com/building-connectors/mcp-servers.md) — turn a third-party MCP server into an Appmixer connector.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/getting-started/appmixer-mcp-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
