> For the complete documentation index, see [llms.txt](https://imbrace.gitbook.io/imbrace-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://imbrace.gitbook.io/imbrace-documentation/connectiq/mcp-server.md). # MCP Server The **MCP** tab in ConnectIQ contains the documentation for the iMBrace MCP Server. The MCP Server uses the Model Context Protocol (MCP) to connect AI tools such as Claude Code, Cursor, Codex CLI and Claude Desktop directly to your iMBrace account. Once connected, your AI tool can work with your iMBrace data on your behalf. For example, it can: * List your CRM boards. * Read conversations. * Check workflow runs. #### Before you start You need two things to connect an AI tool:
RequirementDescription
MCP server URLThe iMBrace gateway hosts the MCP server at the /mcp path. There is nothing to install or run yourself.
API keyAn external token that your AI tool sends as a Bearer token. The AI tool can only access what your organization and user role allow.
> **Note:** The examples in this guide use the sandbox gateway (`https://app-gateway.sandbox.imbrace.co/mcp`). Replace the host with the gateway for your environment. ### Connecting an AI tool #### **Step 1: Generate an API key** 1. Go to **Settings → Generate External Token**. 2. Generate a new external token. 3. Copy the key and store it securely. The key begins with `api_`. For more information, see [**Getting an API Key**](https://engineer.imbrace.co/guides/api-key/). #### **Step 2: Add iMBrace to your AI tool** Select one of the AI tool below and add the configuration. In each example, replace `api_xxx...` with your API key. 1. **Claude Code** Run the following command in your terminal: ``` claude mcp add --transport http imbrace "https://app-gateway.sandbox.imbrace.co/mcp" \ --header "Authorization: Bearer api_xxx..." ``` 2. **Cursor** Add the following `.cursor/mcp.json` to your project. To make iMBrace available in all projects, add `~/.cursor/mcp.json` instead. ```json { "mcpServers": { "imbrace": { "url": "https://app-gateway.sandbox.imbrace.co/mcp", "headers": { "Authorization": "Bearer api_xxx..." } } } } ``` 3. **Codex CLI** For recent versions of Codex that support HTTP MCP servers, add the following `~/.codex/config.toml`: ```toml [mcp_servers.imbrace] url = "https://app-gateway.sandbox.imbrace.co/mcp" bearer_token = "api_xxx..." ``` For older versions of Codex without HTTP support, connect through `mcp-remote` instead: ```toml [mcp_servers.imbrace] command = "npx" args = ["-y", "mcp-remote", "https://app-gateway.sandbox.imbrace.co/mcp", "--header", "Authorization: Bearer api_xxx..."] ``` 4. **Claude Desktop** Claude Desktop runs MCP servers locally, so it connects to iMBrace through `mcp-remote`. 1. In Claude Desktop, go to **Settings → Developer → Edit Config**. 2. Add the following `claude_desktop_config.json` ```json { "mcpServers": { "imbrace": { "command": "npx", "args": [ "-y", "mcp-remote", "https://app-gateway.sandbox.imbrace.co/mcp", "--header", "Authorization: Bearer api_xxx..." ] } } } ``` 5. **Other clients** Any MCP client that accepts a URL and headers can use the standard configuration: ```json { "mcpServers": { "imbrace": { "url": "https://app-gateway.sandbox.imbrace.co/mcp", "headers": { "Authorization": "Bearer api_xxx..." } } } } ``` If your client only supports local (stdio) servers, connect through `mcp-remote`: ``` npx -y mcp-remote "https://app-gateway.sandbox.imbrace.co/mcp" \ --header "Authorization: Bearer api_xxx..." ``` #### **Step 3: Test the connection** Ask your AI tool a question such as: * "List my iMBrace boards" * "Show my latest conversations" If the connection is working, the AI tool will use iMBrace tools such as `listBoards`, `listConversations` and `listFlows` to answer. ### Controlling access By default, the MCP Server is **read-only**. Your AI tool can view data but cannot create, change or delete anything. To allow more access or to limit the AI tool to specific areas, add query parameters to the MCP server URL in your configuration. | Parameter | Effect | | ------------------------------ | ------------------------------------------------------------------- | | `?allowWrite=1` | Allows the AI tool to create and update data. | | `?allowDestructive=1` | Allows the AI tool to delete data. This also includes write access. | | `?services=dataBoard,workflow` | Limits the AI tool to the listed services only. | | `?tags=boards,records` | Limits the AI tool to the listed topics only. | Available services are `dataBoard`, `channel`, `platform`, `marketplace` and `workflow`. To combine parameters, join them with `&`. For example, to give an AI tool write access to data boards only, use: ``` https://app-gateway.sandbox.imbrace.co/mcp?services=dataBoard&allowWrite=1 ``` > **Tip:** Only enable write or delete access when needed. If the AI tool tries to use a tool that is not enabled, it receives a clear error message instead of failing silently. ### How it works Each request from your AI tool is sent through the iMBrace gateway's standard API routes using your API key. This means your organization's scoping, user permissions, and license checks apply exactly as they would if you called the API yourself. The MCP Server uses the same set of agent tools that power the iMBrace SDK. It is a stateless service, so there are no sessions to manage. ### Other ways to connect #### **OpenAPI** Some platforms, such as Open WebUI, use OpenAPI tool specifications instead of MCP. These platforms can connect to: ``` GET /agent-tools/openapi.json ``` Use the same `Authorization` header as the MCP configuration. This returns the agent tools from all services in a single specification, so you only need to add one tool server instead of five. You can use the same `?services=` and `?tags=` filters to limit what is included. #### **iMBrace CLI** If you prefer to run a local server using credentials from your CLI profile, the iMBrace CLI includes the same tools. Run: ``` imbrace mcp ``` ####