> For the complete documentation index, see [llms.txt](https://help.transform.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.transform.ai/integrations/transform-mcp-server.md). # Transform MCP Server Connect Claude, Cursor, ChatGPT and other AI tools to Transform through the Transform MCP server, using OAuth sign-in (recommended) or an API token. ### Overview The Transform MCP server lets external AI tools work with your Transform data. Once connected, a tool such as Claude, Cursor or ChatGPT can search, read, create and update records in Transform on your behalf. All AI tools connect to the same endpoint: ``` https://app.transform.ai/mcp ``` ### Key Concepts * **MCP (Model Context Protocol)**: an open standard that lets AI tools call tools hosted by another service. * **OAuth sign-in**: the AI tool opens a Transform sign-in page in the browser and stores the access it is granted. The access expires and is renewed by signing in again. Recommended for all AI tools that support it. * **API token**: a long-lived secret starting with `mt_`. The AI tool sends it with every request. Less secure than OAuth: because the token stays valid for a long time, anyone who obtains it can use it until it expires or is revoked. * **Scope**: the Account, Organization or Project the connection works in by default. ### Choose a connection method | | OAuth sign-in (recommended) | API token | | --------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | Setup | Click **Connect** in the tool, sign in to Transform | Create a token, paste it into the tool's config | | Stays connected | While you remain signed in to Transform | Until the token expires or is revoked, which can be up to a year or never | | Acts as | You, with your own permissions | A dedicated teammate named after the token, with the role you pick | | Best for | Any AI tool that offers a Connect or Sign in button. Use this first whenever it is available. | Scripts and tools that cannot sign in with OAuth but accept custom headers | {% hint style="info" %} Use OAuth sign-in whenever your AI tool supports it. Use an API token only when the tool cannot sign in with OAuth. API tokens are less secure because they are long-lived: anyone who gets hold of one can use it until it expires or is revoked. {% endhint %} ### Connect with OAuth sign-in (recommended) OAuth sign-in is the recommended and most secure way to connect. Use it whenever your AI tool offers a **Connect** or **Sign in** button. 1. In your AI tool, add a custom MCP server or connector with the URL . 2. Select **Connect**. A Transform sign-in page opens in your browser. 3. Sign in to Transform and approve access. 4. Return to your AI tool. The Transform tools are now available. The tool works as you, with your permissions. {% hint style="info" %} OAuth connections depend on an active Transform session in your browser. If you sign out of Transform, or your session expires, the AI tool may lose access until you reconnect. This is by design: access ends when your session ends, so a lost or forgotten connection does not stay usable the way a long-lived API token does. {% endhint %} ### Connect with an API token (alternative) Use an API token only when your AI tool cannot sign in with OAuth, for example a script or a tool that only accepts custom HTTP headers. {% hint style="warning" %} API tokens are less secure than OAuth sign-in because of their longevity. A token is a long-lived secret: anyone who obtains it, for example from a config file, a log or source control, can use it until it expires or is revoked. A token set to Never expire stays valid indefinitely. Prefer OAuth sign-in, and if you must use a token, pick the shortest expiration that works and revoke it as soon as it is no longer needed. {% endhint %} Prerequisites: * A Transform role that allows creating API tokens * An AI tool that supports remote MCP servers with custom headers {% stepper %} {% step %} ### Create an API token 1. In Transform, open **Account Settings → API Tokens**, or go to [app.transform.ai/account/api-tokens](https://app.transform.ai/account/api-tokens). 2. Select **Create Token**. 3. Enter a **Name** that describes the connection, such as `Claude Code - Jose`. 4. Pick a **Role**. The token can do only what this role allows. 5. Pick an **Expiration**: 1 hour, 24 hours, 7 days, 30 days (default), 90 days, 1 year or Never. Choose the shortest expiration that works and avoid Never: the longer a token lives, the longer a leaked token can be misused. 6. Select **Create Token**. {% hint style="warning" %} The full token is shown only once. Copy it now and store it somewhere safe, such as a password manager. It cannot be retrieved after the dialog closes. {% endhint %} The token acts as a dedicated teammate named after the token, not as you. Its actions appear under that name in activity and history. {% endstep %} {% step %} ### Add Transform to your AI tool Configure a remote (HTTP) MCP server with: * **URL**: `https://app.transform.ai/mcp` * **Header**: `Authorization: Bearer ` Generic configuration: ```json { "url": "https://app.transform.ai/mcp", "headers": { "Authorization": "Bearer mt_your_token_here" } } ``` **Claude Code** ```bash claude mcp add --transport http transform https://app.transform.ai/mcp --header "Authorization: Bearer mt_your_token_here" ``` **Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json` in a project) ```json { "mcpServers": { "transform": { "url": "https://app.transform.ai/mcp", "headers": { "Authorization": "Bearer mt_your_token_here" } } } } ``` For other tools, look for a setting named "remote MCP server", "HTTP MCP" or "custom connector" that accepts headers. {% endstep %} {% step %} ### (Optional) Limit the connection to an Organization or Project By default, the connection works across your whole Account. To focus it on one Organization or Project, add two more headers: ```json { "url": "https://app.transform.ai/mcp", "headers": { "Authorization": "Bearer mt_your_token_here", "x-scope": "project", "x-scope-id": "" } } ``` | Header | Values | Notes | | ------------ | -------------------------------------- | ------------------------------------------------------- | | `x-scope` | `account`, `organization` or `project` | Optional. Defaults to `account`. | | `x-scope-id` | The Organization or Project ID | Required when `x-scope` is `organization` or `project`. | To find an ID, open the Organization or Project in Transform and copy it from the address bar: * Organization: `app.transform.ai/organizations/` * Project: `app.transform.ai/organizations//projects/` The scope sets the default context for the AI tool, for example which Organization "list my projects" refers to. It does not grant extra access. The token's role still decides what can be read or changed. {% endstep %} {% step %} ### Test the connection Ask your AI tool something read-only first, for example: > Using Transform, list the projects I have access to. If it returns your projects, the connection is working. {% endstep %} {% endstepper %} ### What the AI tool can do The MCP server exposes the same capabilities as the Transform agent, limited by the permissions of the connected user or token: * **Ask Transform**: send a natural-language question to the Transform agent (`ask_transformAgent`). Each call is independent and has no memory of earlier calls. * **Explore your data model**: list entities, fields, custom fields, statuses and types (`describeEntityTool`, `listCustomFieldDefinitionsTool`, `listStatusLabelsTool`). * **Search and read records**: query any entity, read records, long text fields and relations (`dynamicQueryTool`, `getRecordTool`). * **Create and update records**: create, update, archive, restore and delete records, and link records to each other. * **Organizations, Projects and Teammates**: list and find Organizations, Projects and Teammates. * **Meetings**: read meetings and search transcripts, and create or update meetings. * **Artifacts and attachments**: create and read artifacts, and read record attachments. * **Saved views and dashboards**: list and read saved views, save Explorer queries, create dashboards and add widgets. * **GitHub**: when GitHub is connected to your Account, browse repositories and pull requests. {% hint style="info" %} AI tools work best when they check the data model first. If results look wrong, ask the tool to describe the entity (for example "describe the Requirement entity in Transform") before querying or writing. {% endhint %} #### Actions that need approval in Transform Some sensitive actions require an approval card that can only be confirmed inside Transform. External AI tools cannot complete them, and they are cancelled rather than run. These include: * Bulk updates to many records at once * Creating, publishing or deleting saved views * Archiving or restoring Organizations and Projects * Creating or changing Goals, Periods and Routines, and running a Routine now * Starting GitHub coding or review runs Use Console in Transform for these actions. ### Troubleshooting #### 401 "Unauthorized: Missing Authorization header" The AI tool did not send a token. Check that the `Authorization` header is set and starts with `Bearer` , with a space after `Bearer`. #### 401 "Invalid or expired CLI token" The API token was mistyped, has expired or was revoked, or its teammate was disabled. Check the token in **Account Settings → API Tokens**. If needed, create a new token and update your AI tool. #### 401 "Invalid or expired token" The OAuth access has expired. Reconnect the AI tool to Transform. #### 403 "No active session found for user" The OAuth connection lost its Transform session, usually after signing out of Transform or after the session expired. Sign in to Transform in your browser and reconnect, or switch to an API token. #### 403 "Access denied: organization scope is not readable" or "project scope is not readable" The `x-scope-id` is wrong, or the token's role cannot see that Organization or Project. Copy the ID again from the address bar and confirm the role has access. #### 400 "x-scope-id is required" or "Invalid x-scope value" `x-scope` must be `account`, `organization` or `project`. When it is `organization` or `project`, also send `x-scope-id`. #### API Tokens is not visible in Account Settings Your role may not allow creating API tokens, or API tokens may not be enabled for your Account. Ask an Account Admin or contact support. #### An action was "not confirmed" or cancelled The action requires approval in Transform. See [Actions that need approval in Transform](#actions-that-need-approval-in-transform). ### Best Practices * Create one token per tool or person, so each can be revoked on its own. * Give each token the least-privileged role that covers the work. * Prefer an expiration over **Never**, and rotate tokens before they expire. * Never commit tokens to source control. Use environment variables or a secrets manager where your tool supports them. * Revoke a token as soon as it is no longer needed. Requests using it stop working immediately. ### Summary Connect any MCP-capable AI tool to `https://app.transform.ai/mcp`. Use OAuth sign-in whenever your AI tool supports it. It is the recommended and more secure method. Use an API token in the Authorization header only when OAuth is not available, because long-lived tokens are less secure. Add `x-scope` and `x-scope-id` to focus the connection on an Organization or Project. --- # 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://help.transform.ai/integrations/transform-mcp-server.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.