> 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.

To use the MCP server, you must have a Fabricate account.

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://<your-fabricate-host>/api/v1/mcp
```

Where `<your-fabricate-host>` is the location where the Fabricate instance is deployed.

On Fabricate Cloud, the host is `fabricate.tonic.ai`.

On a self-hosted instance, the host is the value of `FABRICATE_HOST`.

## 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 %}

### 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.

<table><thead><tr><th width="301.3125" valign="top">Scope</th><th valign="top">Allows the AI client to</th></tr></thead><tbody><tr><td valign="top"><code>fabricate:mcp:read</code></td><td valign="top"><p>Read:</p><ul><li>Data generation runs</li><li>Status values</li><li>Chat transcripts</li><li>Generated artifacts</li><li>Workflows</li><li>Lists</li></ul></td></tr><tr><td valign="top"><code>fabricate:mcp:project:edit</code></td><td valign="top"><p>Perform any change within a project, including:</p><ul><li>Start and continue generation</li><li>Revert changes</li><li>Run workflows</li><li>Cancel generation</li><li>Upload files</li></ul></td></tr><tr><td valign="top"><code>fabricate:mcp:project:create</code></td><td valign="top">Create projects, including the implicit project that is created automatically when you start a conversation.</td></tr></tbody></table>

#### 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.

<table><thead><tr><th width="329.22265625">Scope</th><th>Allows the AI client to</th></tr></thead><tbody><tr><td><code>fabricate:mcp:project:delete</code></td><td>Delete a project and its data.</td></tr><tr><td><code>fabricate:mcp:workspace:create</code></td><td>Create workspaces.</td></tr><tr><td><code>fabricate:mcp:workspace:delete</code></td><td>Delete a workspace and everything in it.</td></tr></tbody></table>

## 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://<your-fabricate-host>/api/v1/mcp",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}
```

## 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tonic.ai/fabricate/fabricate-api/using-the-fabricate-mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.