> For the complete documentation index, see [llms.txt](https://docs.tonic.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tonic.ai/fabricate/fabricate-api/using-the-fabricate-mcp-server.md). # Using the Fabricate MCP server The Fabricate Model Context Protocol (MCP) server allows AI clients to communicate directly with the Fabricate Data Agent. AI clients can use the MCP connection to create databases, run workflows, and download data generation results. Account owners can also use the MCP connection to list users and groups, list API keys, track usage and cost, and get audit log information. To use the MCP server, you must have a Fabricate account. If you do not already have an account, then for information on how to sign up for an account under the free license plan, go to [Starting a Fabricate account](/fabricate/fabricate-accounts-and-users/fabricate-getting-started.md). To authenticate to the MCP server, you can use either: * **OAuth** — Recommended for interactive clients such as Claude and Cursor. * **API key** — Recommended for scripts or continuous integration (CI) that is not tied to a specific user. Fabricate is both the OAuth 2.1 authorization server and the resource server for the MCP. Every request to the MCP carries either an API key or an OAuth access token in the `Authorization` header. ## MCP server endpoint The MCP server uses the MCP Streamable HTTP transport (JSON‑RPC 2.0). The MCP server endpoint is: ``` POST https:///api/v1/mcp ``` Where `` is the location where the Fabricate instance is deployed. On Fabricate Cloud, the host is `fabricate.tonic.ai`, so: {% code overflow="wrap" %} ``` POST https://fabricate.tonic.ai/api/v1/mcp ``` {% endcode %} On a self-hosted instance, the host is the value of `FABRICATE_HOST`. ## Setting up the connection to your AI client The following information explains how to use OAuth to connect common AI clients to Fabricate. OAuth is the recommended authentication method for interactive clients. The examples use the Fabricate Cloud endpoint - `https://fabricate.tonic.ai/api/v1/mcp`. On a self-hosted instance, replace `fabricate.tonic.ai` with the value of `FABRICATE_HOST.` When you first connect, Fabricate prompts you in your browser to sign in and approve access. For information on how to complete this step: * If you use OAuth, go to [#completing-the-oauth-authentication](#completing-the-oauth-authentication "mention"). * To instead use an API key, go to [#api-key-authentication](#api-key-authentication "mention"). ### Claude Code To add the Fabricate MCP server to Claude Code: 1. Run:\ \ `claude mcp add --transport http fabricate https://fabricate.tonic.ai/api/v1/mcp` 2. In Claude Code, run `/mcp`. 3. Follow the browser prompts to sign in to Fabricate and approve access. ### Claude On a Team or Enterprise plan, an owner must first add the connector under **Organization settings > Connectors**. Other users can then connect to it from **Customize > Connectors**. To add Fabricate as a custom connector in Claude: 1. Go to **Customize > Connectors**. 2. Click **+ Add**, then click **Add custom connector**. 3. Enter the name `Fabricate`. 4. Paste the server URL `https://fabricate.tonic.ai/api/v1/mcp`, then click **Continue**. 5. Review the authentication settings that Claude detects. 6. Click **Continue**, then click **Add**. 7. When prompted, sign in to Fabricate and approve access. 8. To use the connector in a chat: 1. Click **+** at the lower left of the chat. 2. Click **Connectors**. 3. Turn on the Fabricate connector. ### Cursor #### Connecting the Fabricate MCP server to Cursor To add the Fabricate MCP server to Cursor for all projects, add it to `~/.cursor/mcp.json`. To instead add the Fabricate MCP server to a specific project, in that project, use `.cursor/mcp.json`. In the file, under `mcpServers`, add the `fabricate` server: {% code overflow="wrap" %} ``` { "mcpServers": { "fabricate": { "url": "https://fabricate.tonic.ai/api/v1/mcp" } } } ``` {% endcode %} #### Connecting to the fabricate server After you save the file: 1. From Cursor's MCP settings, connect to the `fabricate` server. 2. In your browser, sign in to Fabricate. #### Using mcp-remote instead of OAuth If your version of Cursor does not support OAuth for remote servers, use `mcp-remote` instead. In that case, the `fabricate` entry looks like this: {% code overflow="wrap" %} ``` { "mcpServers": { "fabricate": { "command": "npx", "args": [ "mcp-remote", "https://fabricate.tonic.ai/api/v1/mcp" ] } } } ``` {% endcode %} For more information, go to [#configuring-remote-authentication-from-your-ai-client](#configuring-remote-authentication-from-your-ai-client "mention"). ### VS Code To connect to the Fabricate MCP server from VS Code, use one of the following options. #### Run MCP: Add Server To add the Fabricate MCP server: 1. From the Command Palette, run `MCP: Add Server`. 2. Select **HTTP**. 3. Enter `https://fabricate.tonic.ai/api/v1/mcp`. 4. Follow the prompts. #### Add the server to your workspace To add the Fabricate MCP server to your workspace, edit `.vscode/mcp.json` to add the `fabricate` server. {% code overflow="wrap" %} ``` { "servers": { "fabricate": { "type": "http", "url": "https://fabricate.tonic.ai/api/v1/mcp" } } } ``` {% endcode %} When VS Code connects to the server, in your browser, Fabricate prompts you to sign in and approve access. #### Add the server to your user profile To add the Fabricate MCP server to your user profile: 1. Run `MCP: Open User Configuration`. 2. Edit `mcp.json` to add the `fabricate` server: {% code overflow="wrap" %} ``` { "servers": { "fabricate": { "type": "http", "url": "https://fabricate.tonic.ai/api/v1/mcp" } } } ``` {% endcode %} When VS Code connects to the server, in your browser, Fabricate prompts you to sign in and approve access. ## OAuth authentication {% hint style="warning" %} If you use OAuth authentication, do not provide a Fabricate API key in the Authorization header. Only use one authentication method. {% endhint %} ### Configuring remote authentication from your AI client If your AI client does not support remote authorized servers, then in your AI client settings file, add an `mcp-remote` entry for Fabricate. For example: {% code overflow="wrap" %} ``` "remote-example": { "command": "npx", "args": [ "mcp-remote", "https:///api/v1/mcp" ] } ``` {% endcode %} ### Completing the OAuth authentication When you first connect to the MCP server: 1. In your browser, Fabricate prompts you to authorize access. 2. If needed, sign in to Fabricate. 3. Confirm the account. 4. Review the permissions to grant. 5. Approve the access. Your AI client stores the resulting token and uses it to connect to Fabricate. For each subsequent request, Fabricate verifies that the token is still valid for the account. ### OAuth token scopes OAuth tokens carry scopes that limit the available actions that can be performed. They cannot expand the existing permissions for your Fabricate account, but they can add limits. #### Default scopes The following scopes are requested by default, if the request does not specify any scopes.
ScopeAllows the AI client to
fabricate:mcp:read

Read:

  • Data generation runs
  • Status values
  • Chat transcripts
  • Generated artifacts
  • Workflows
  • Lists
fabricate:mcp:project:edit

Perform any change within a project, including:

  • Start and continue generation
  • Revert changes
  • Run workflows
  • Cancel generation
  • Upload files
fabricate:mcp:project:createCreate projects, including the implicit project that is created automatically when you start a conversation.
#### Elevated scopes Because these scopes enable destructive actions, you must specifically enable them during authentication. They are included in the list of permissions to review.
ScopeAllows the AI client to
fabricate:mcp:project:deleteDelete a project and its data.
fabricate:mcp:workspace:createCreate workspaces.
fabricate:mcp:workspace:deleteDelete a workspace and everything in it.
## API key authentication When you use a Fabricate API key for authentication, the permissions are based on the API key. For example, if an API key is limited to specific workspaces, then you can only use the MCP server to perform actions within those workspaces. To use API key authentication: 1. [Create an API key in Fabricate](/fabricate/fabricate-api/managing-fabricate-api-keys.md). 2. Pass in the API as a bearer token: ``` { "mcpServers": { "fabricate": { "url": "https:///api/v1/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ## Workflow for the MCP connection After you complete the authentication, a typical workflow is as follows: 1. `start_conversation` - Starts a new Agent chat. You provide a plain‑English instruction for the Agent. Returns a `conversation_id` immediately.\ \ By default, requests to the MCP server use Autonomous mode. You can optionally provide a `mode` (`autonomous`, `agent`, `plan`) to set the [mode](/fabricate/data-agent-tools/data-agent-modes-and-models.md) for the Agent to use. 2. `get_conversation_status` - If the status is `running`, polls until a terminal `status` (`completed`, `failed`, `cancelled`) is reached. 3. `get_conversation_result` - Reads the agent's summary, generated databases, and generated files. 4. `download_conversation_file` - Gets a download URL for an exported file. If you do not provide a `project_id`/`workspace_name`, `start_conversation` runs in the first workspace you can edit and creates a project automatically. Here is an example of a call to start a new conversation: ``` { "name": "start_conversation", "arguments": { "message": "Create 100 users with firstName, lastName, email." } } ``` --- # 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.tonic.ai/fabricate/fabricate-api/using-the-fabricate-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.