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, so:

POST https://fabricate.tonic.ai/api/v1/mcp

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

OAuth authentication

If you use OAuth authentication, do not provide a Fabricate API key in the Authorization header.

Only use one authentication method.

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:

"remote-example": {
  "command": "npx",
  "args": [
        "mcp-remote",
        "https://<your-fabricate-host>/api/v1/mcp"
      ]
}

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.

Scope	Allows 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:create	Create 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.

Scope	Allows the AI client to
fabricate:mcp:project:delete	Delete a project and its data.
fabricate:mcp:workspace:create	Create workspaces.
fabricate:mcp:workspace:delete	Delete 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.
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 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." } }