> 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/connector-configuration/mcp-gateway.md). # MCP Gateway appmixer.ai.mcptools The *MCP Gateway* component (`appmixer.ai.mcptools.MCPGateway`, category *AI* > *MCP Tools*) turns an Appmixer flow into a set of tools for MCP clients such as Claude Code, Claude Desktop, Cursor, VS Code or Windsurf. Every action component you connect to its `tool` output port becomes a tool that the model can call. The MCP client doesn't connect to the gateway directly. It runs the **Appmixer MCP Server** ([`appmixer-mcp`](https://github.com/Appmixer-ai/appmixer-mcp)) on your computer, and that server finds the gateways in your running flows and forwards tool calls to them. You don't need to register an OAuth app. The MCP server signs in as an Appmixer user. {% hint style="warning" %} `appmixer-mcp` is a local (stdio) MCP server. Claude on the web (claude.ai custom connectors) accepts only remote MCP servers, so it can't use the gateway. Use Claude Code, Claude Desktop or another client that runs local MCP servers. {% endhint %} ## How it works 1. When a flow with the MCP Gateway starts, the gateway builds tool definitions from the components on its `tool` port. It then registers them with its webhook URL for the owner of the flow. 2. `appmixer-mcp` reads the gateways registered for the user it signs in as (`GET /plugins/appmixer/ai/mcptools/gateways`) and offers their tools to the MCP client. It also listens for gateways being added or removed (`/plugins/appmixer/ai/mcptools/events`). 3. When the model calls a tool, `appmixer-mcp` sends the call to the gateway webhook. The gateway runs the component and returns its output as the tool result. ## Before you start * The MCP Tools module (`appmixer.ai.mcptools`) installed on your Appmixer tenant. Its plugin provides the endpoints above. * Node.js 20 or newer on the computer where the MCP client runs. * The API URL of your tenant, e.g. `https://api.YOUR_TENANT.appmixer.cloud`. This is not the URL of the Studio. * An Appmixer user. `appmixer-mcp` sees only the gateways in flows that this user owns. ## Build the flow 1. Create a flow and add *MCP Gateway* from *AI* > *MCP Tools*. 2. Connect the action components you want to expose to the gateway's `tool` output port. You can also connect Appmixer MCP servers (`appmixer.mcpservers.*`). Each tool of an MCP server becomes a separate tool. 3. Configure each connected component: * **Fields the model fills:** insert the *Model Defined Parameter* variable of the `tool` port. These fields become the parameters of the tool. * **Fixed fields:** type the value. It's sent on every call and the model can't change it. * **Variables from other components** don't work here. A tool call runs only the connected component, so these values never exist, and the gateway ignores such fields. 4. Rename each connected component to say what the tool does, e.g. *Create support ticket*. The name becomes part of the tool name. 5. Start the flow. The tools exist only while the flow is running. What the model sees: * **Tool name:** `_`, e.g. `2oRMgurHVxbLEUavJPTjmE_Create_support_ticket`. Characters other than letters, digits and `_` are replaced with `_`, and the name is limited to 64 characters. * **Tool description:** the description of the component type. * **Parameter description:** the label and tooltip of the field in the component inspector. A parameter is required if the field is required in the component. {% hint style="info" %} The tool definitions are built when the flow starts. After you change the components on the `tool` port, stop the flow and start it again. {% endhint %} The `out` port of the gateway sends one message when the flow starts: the webhook URL, the component ID, the flow ID and the list of tools. MCP clients don't need it. Use it when the rest of the flow needs to know the gateway, for example to send its webhook URL somewhere. ## Get Appmixer credentials `appmixer-mcp` signs in with an access token, or with a username and password. * **Access token:** get one by signing in through the API. The response contains `token`. ```bash curl -s -X POST https://api.YOUR_TENANT.appmixer.cloud/user/auth \ -H 'Content-Type: application/json' \ -d '{"username":"you@example.com","password":"YOUR_PASSWORD"}' ``` The token expires after the period set in `GRIDD_JWT_TOKEN_EXP` (30 days by default). After that you have to replace it in the client configuration. * **Username and password:** `appmixer-mcp` gets the token by itself and gets a new one when it expires. This is the better choice for a setup that runs for a long time. ## Configuration `appmixer-mcp` reads these environment variables: * `APPMIXER_BASE_URL` (required): the API URL of your tenant. * `APPMIXER_ACCESS_TOKEN`: the access token. Required unless you set the username and password. * `APPMIXER_USERNAME`, `APPMIXER_PASSWORD`: the credentials used to get and renew the token. * `TOOLS`: which tools to offer, `api,mcpgateway` by default. * `mcpgateway`: the tools of your MCP Gateways. * `api`: tools that manage your flows. They list, start, stop and **delete** flows, trigger components, send app events and read flow logs. {% hint style="warning" %} Set `TOOLS=mcpgateway` unless you want the model to manage your flows. With the default value the model also gets a tool that deletes flows. {% endhint %} ## Connect Claude Code ```bash claude mcp add appmixer -s user \ -e APPMIXER_BASE_URL=https://api.YOUR_TENANT.appmixer.cloud \ -e APPMIXER_ACCESS_TOKEN=YOUR_TOKEN \ -e TOOLS=mcpgateway \ -- npx -y appmixer-mcp ``` * Put the options after the server name and the command after `--`. * `-s user` adds the server to all your projects. Leave it out to add it to the current project only. * Run `/mcp` in Claude Code to see the status of the server and its tools. More in the Claude Code documentation: [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp). ## Connect Claude Desktop 1. Open *Settings* > *Developer* and click *Edit Config*. This opens `claude_desktop_config.json`: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` 2. Add the server: ```json { "mcpServers": { "appmixer": { "command": "npx", "args": ["-y", "appmixer-mcp"], "env": { "APPMIXER_BASE_URL": "https://api.YOUR_TENANT.appmixer.cloud", "APPMIXER_USERNAME": "you@example.com", "APPMIXER_PASSWORD": "YOUR_PASSWORD", "TOOLS": "mcpgateway" } } } } ``` 3. Quit Claude Desktop and start it again. *Settings* > *Developer* shows the `appmixer` server and whether it's running. {% hint style="info" %} Claude Desktop doesn't load your shell profile when it starts the server. If you use nvm or another Node.js version manager and the server doesn't start, set `command` to the absolute path of `npx` (run `which npx`). {% endhint %} ## Other MCP clients Cursor, VS Code, Windsurf and other MCP clients run the same command (`npx -y appmixer-mcp`) with the same environment variables. The [appmixer-mcp README](https://github.com/Appmixer-ai/appmixer-mcp#readme) shows the configuration for each of them. ## Check the connection * In Claude Code, `/mcp` lists the `appmixer` server with the tools of your running gateways. * Without an MCP client, list the gateways registered for your user: ```bash curl -s https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/ai/mcptools/gateways \ -H "Authorization: Bearer YOUR_TOKEN" ``` Each running gateway is one entry with `flowId`, `componentId`, `webhook` and `tools`. ## Security * A tool call runs the component with the connected accounts of the flow owner. Anyone who has the token or the credentials used by `appmixer-mcp` can call the tools. * Expose only the actions you are fine with the model running. Set the fields that must not change (e.g. a recipient or a project) as fixed values instead of leaving them to the model. ## Troubleshooting * **The server doesn't start with "Base URL is required" or "Either access token or username and password are required".** The client configuration is missing `APPMIXER_BASE_URL`, or both the token and the username and password. * **The server runs but offers no gateway tools.** * The flow with the gateway isn't running. * The flow belongs to a different user than the one `appmixer-mcp` signs in as. * `TOOLS` doesn't include `mcpgateway`. * The MCP Tools module isn't installed on the tenant. The `gateways` request in [Check the connection](#check-the-connection) returns 404. * **The tools don't change after a flow starts or stops.** `appmixer-mcp` notifies the client, but not every client reloads its tool list. Reconnect the server (`/mcp` in Claude Code) or restart Claude Desktop. * **Requests fail with "Unauthorized".** The access token has expired. Get a new one, or set the username and password instead. * **A tool call fails with "Failed to fetch … Not Found".** The flow was stopped, or the client is using an old tool list. Reload the tools as described above. * **A tool returns "Error calling tool …".** The component itself failed, e.g. because a required field is empty or a connected account has expired. The text includes the error of the component, and the flow logs in Appmixer have the details. * **Tools of a deleted flow are still listed.** If a flow is removed without its gateway being stopped, the gateway stays registered. Remove it: ```bash curl -s -X DELETE "https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/ai/mcptools/gateways/COMPONENT_ID?flowId=FLOW_ID" \ -H "Authorization: Bearer YOUR_TOKEN" ``` * **Server logs:** Claude Desktop writes the output of the server to `~/Library/Logs/Claude/mcp-server-appmixer.log` on macOS and `%APPDATA%\Claude\logs\` on Windows. More about local MCP servers: [Connect to local MCP servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers). --- # 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/connector-configuration/mcp-gateway.md?ask=&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.