---
title: "MCP Server | UnifiedData"
description: "Connect Claude, ChatGPT, Cursor, VS Code, Codex and other AI clients to UnifiedData over MCP: setup guides, tools, permissions and security."
url: https://unifieddata.ai/mcp
---

Model Context Protocol

# UnifiedData MCP server

Build, test and run UnifiedData flows by asking your AI assistant. It can read both apps’ fields, draft a mapping, preview it on a real record and turn the flow on.

**On this page:**Quick start · What you can do · Connect your client · Sign-in and permissions · Tools · Example prompts · Security · Troubleshooting · For client developers

## Quick start

Add this URL to your AI client as a custom connector or remote MCP server:

https://api.unifieddata.io/data/mcp

1.  Add the URL to your client. Pick your client in Connect your client.
2.  Your client opens a browser window. Sign in to UnifiedData (or [sign up free](https://app.unifieddata.ai/)), choose a workspace and approve the permissions it asks for.
3.  Ask for what you need. The assistant acts with your role in that workspace and nothing more.

Server URL

`https://api.unifieddata.io/data/mcp`

Transport

Streamable HTTP (remote). Nothing to install.

Authentication

OAuth 2.1 sign-in with your UnifiedData account, or a workspace API key.

MCP versions

2026-07-28, plus earlier revisions back to 2025-03-26

Tools

22 tools

## What you can do

-   **Connect apps:** list the apps you can connect, create a link to connect a new one, and inspect the objects, fields and live records of your connections.
-   **Build flows:** create flows from a source app to one or more destination apps or a database, with field mappings, and activate or pause them.
-   **Test safely:** preview a mapping on a real record and dry-run a flow on sample records. Neither writes anything.
-   **Run and troubleshoot:** trigger a flow now and read its run history, record by record.

## Connect your client

These steps add the UnifiedData management server. Menus move between releases, so check your client’s own MCP documentation if a step does not match.

Claude (claude.ai and Claude Desktop)Claude CodeChatGPTOpenAI Codex (CLI and IDE extension)CursorVS Code (GitHub Copilot)WindsurfGemini CLIZedClineJetBrains IDEs (AI Assistant)Other clients

### Claude (claude.ai and Claude Desktop)

1.  Open **Settings → Connectors** and choose **Add custom connector**.
2.  Name it `UnifiedData` and paste the server URL.
3.  Click **Connect**, sign in to UnifiedData, choose a workspace and approve access.
4.  In a chat, enable UnifiedData from the tools menu.

On Team and Enterprise plans, an owner may need to add the connector for the organization first.

### Claude Code

claude mcp add --transport http unifieddata https://api.unifieddata.io/data/mcp

Then run `/mcp` inside Claude Code, select **unifieddata** and choose **Authenticate**. Add `--scope project` to share it with your team through `.mcp.json`, or `--scope user` to use it in every project.

### ChatGPT

1.  Turn on **Developer mode** under **Settings → Apps & Connectors → Advanced settings**.
2.  Back in **Apps & Connectors**, choose **Create**.
3.  Name it `UnifiedData`, paste the server URL and choose **OAuth** authentication.
4.  Sign in to UnifiedData and approve access, then enable it from the tools menu in a chat.

### OpenAI Codex (CLI and IDE extension)

codex mcp add unifieddata --url https://api.unifieddata.io/data/mcp
codex mcp login unifieddata

Or add it to `~/.codex/config.toml` and then run `codex mcp login unifieddata`:

\[mcp\_servers.unifieddata\]
url = "https://api.unifieddata.io/data/mcp"

### Cursor

Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project), then open **Settings → MCP** and click **Connect** next to unifieddata:

{
  "mcpServers": {
    "unifieddata": {
      "url": "https://api.unifieddata.io/data/mcp"
    }
  }
}

### VS Code (GitHub Copilot)

code --add-mcp '{"name":"unifieddata","type":"http","url":"https://api.unifieddata.io/data/mcp"}'

Or add it to `.vscode/mcp.json` (or run **MCP: Add Server** from the Command Palette). Start the server when prompted and sign in, then use it from Copilot Chat in **Agent** mode.

{
  "servers": {
    "unifieddata": {
      "type": "http",
      "url": "https://api.unifieddata.io/data/mcp"
    }
  }
}

### Windsurf

Open **Windsurf Settings → Cascade → MCP Servers → View raw config** (`~/.codeium/windsurf/mcp_config.json`), add the server and refresh:

{
  "mcpServers": {
    "unifieddata": {
      "serverUrl": "https://api.unifieddata.io/data/mcp"
    }
  }
}

### Gemini CLI

gemini mcp add --transport http unifieddata https://api.unifieddata.io/data/mcp

Or add it to `~/.gemini/settings.json`. Then run `/mcp auth unifieddata` inside Gemini CLI to sign in:

{
  "mcpServers": {
    "unifieddata": {
      "httpUrl": "https://api.unifieddata.io/data/mcp"
    }
  }
}

### Zed

Add a context server to your Zed `settings.json`. This uses the mcp-remote bridge, which handles the browser sign-in:

{
  "context\_servers": {
    "unifieddata": {
      "command": "npx",
      "args": \[
        "-y",
        "mcp-remote",
        "https://api.unifieddata.io/data/mcp"
      \]
    }
  }
}

### Cline

Open the **MCP Servers** panel, choose **Configure** to edit `cline_mcp_settings.json`, and add:

{
  "mcpServers": {
    "unifieddata": {
      "command": "npx",
      "args": \[
        "-y",
        "mcp-remote",
        "https://api.unifieddata.io/data/mcp"
      \]
    }
  }
}

### JetBrains IDEs (AI Assistant)

Go to **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**, click **Add**, choose **As JSON** and paste:

{
  "mcpServers": {
    "unifieddata": {
      "command": "npx",
      "args": \[
        "-y",
        "mcp-remote",
        "https://api.unifieddata.io/data/mcp"
      \]
    }
  }
}

### Other clients

Any client that supports remote Streamable HTTP servers with OAuth can use the server URL directly. For a client that only runs local (stdio) servers, or cannot do OAuth, bridge it with [mcp-remote](https://www.npmjs.com/package/mcp-remote) (needs Node.js 18+). It opens the browser sign-in on first use and stores the token locally:

{
  "mcpServers": {
    "unifieddata": {
      "command": "npx",
      "args": \[
        "-y",
        "mcp-remote",
        "https://api.unifieddata.io/data/mcp"
      \]
    }
  }
}

## Sign-in and permissions

### OAuth (recommended)

-   Your client signs you in to UnifiedData in the browser. On the consent screen you choose the workspace the client may use and approve the scopes it asks for. Its access is tied to that workspace.
-   Every tool runs with your own role in the workspace (viewer, member, admin or owner), checked on every call. If you leave the workspace, the client loses access at once.
-   A client approved for UnifiedData cannot use another product’s management server; each has its own URL and sign-in.

### Workspace API key

Clients that can’t do OAuth can send a workspace API key as a bearer token. The workspace owner creates it in the app under [Settings → API Access](https://app.unifieddata.ai/settings/api). It acts as the owner with every permission, so prefer OAuth where you can and keep the key secret.

Authorization: Bearer ud\_…

# Claude Code
claude mcp add --transport http unifieddata https://api.unifieddata.io/data/mcp --header "Authorization: Bearer ud\_…"

### Scopes

Scope

Allows

`connections:read`

See your connected apps and the objects and fields they expose.

`connections:write`

Create links to connect new apps, and remove connections.

`flows:read`

Read your flows, their field mappings and their run history.

`flows:write`

Create, change, activate, pause and delete flows.

`flows:run`

Trigger flows, which reads and writes data in your connected apps.

A tool also needs the right workspace role. The tables below list the minimum role; your role is checked as well as the scope.

## Tools

22 tools. Tools marked **Changes data** are flagged as destructive, so most clients ask before running them; ones marked **Confirm** also need `confirm: true`.

### Connected apps

Tool

What it does

Scope

Role

Changes data

`list_integrations`

Apps you can connect, optionally filtered by category (crm, hris, ats, ticketing, accounting, …).

`connections:read`

viewer

No

`list_connections`

Apps connected to the workspace, filtered by category or status.

`connections:read`

viewer

No

`get_connection`

One connection: its app, categories, permissions and status.

`connections:read`

viewer

No

`list_connection_objects`

The object types a connection supports, and which can send webhooks.

`connections:read`

viewer

No

`get_object_fields`

The fields of one object type, and whether each can be read or written.

`connections:read`

viewer

No

`list_records`

Read a few live records (up to 25) from a connected app. Never writes.

`connections:read`

viewer

No

`create_connection_link`

A link a person opens to connect a new app.

`connections:write`

member

Yes

`delete_connection`

Disconnect an app. Refused while an active flow reads from it.

`connections:write`

admin

Yes · Confirm

### Flows

Tool

What it does

Scope

Role

Changes data

`list_flows`

Your flows, newest first, with source, destinations, status and last run.

`flows:read`

viewer

No

`get_flow`

One flow in full.

`flows:read`

viewer

No

`create_flow`

Copy one object type from a source app to one or more destinations. New flows start paused.

`flows:write`

member

Yes

`update_flow`

Change a flow’s name, mapping, destinations or database destination.

`flows:write`

member

Yes

`activate_flow`

Turn a flow on and start listening for changes in the source app.

`flows:write`

member

Yes

`pause_flow`

Turn a flow off. Changes made while paused are not synced later.

`flows:write`

member

Yes

`delete_flow`

Delete a flow. Its run history is kept.

`flows:write`

admin

Yes · Confirm

### Test and run

Tool

What it does

Scope

Role

Changes data

`test_flow`

Dry run on up to 3 real source records. Writes nothing.

`flows:read`

viewer

No

`trigger_flow`

Run an active flow now. Writes real records.

`flows:run`

member

Yes

`list_flow_runs`

Run history, for all flows or one.

`flows:read`

viewer

No

`get_flow_run`

The outcome of one run, record by record.

`flows:read`

viewer

No

### Field mappings

Tool

What it does

Scope

Role

Changes data

`get_default_mapping`

The built-in mapping between two object types.

`flows:read`

viewer

No

`validate_mapping`

Check a mapping’s expressions for errors.

`flows:read`

viewer

No

`preview_mapping`

Apply a mapping to sample data or a real record. Writes nothing.

`flows:read`

viewer

No

## Example prompts

-   “Sync new HubSpot contacts into Salesforce leads, and show me a preview first.”
-   “Why did last night’s run of my BambooHR flow have failures?”
-   “Pause every flow that writes to our old Postgres database.”
-   “Which fields can I write on a Zendesk ticket?”

## Good to know

-   Tool results are capped at 100,000 characters so they don’t flood your assistant’s context. List tools page through results (`page`, and `limit` up to 100).
-   `test_flow` and `preview_mapping` never write. `trigger_flow` writes real records, and a new flow stays paused until `activate_flow`.
-   The API allows up to 100 requests a minute from one IP address, MCP included.
-   Plan limits and your workspace role apply exactly as in the app. See [Pricing](https://unifieddata.ai/pricing.md).

## Security and revoking access

-   Access tokens last one hour and only work with the server they were issued for. Refresh tokens last 30 days and are replaced every time they are used; reusing an old one revokes every token descended from it.
-   Every sign-in uses PKCE (S256), so a stolen authorization code cannot be redeemed.
-   To stop a client using your account, disconnect or remove UnifiedData in that client. Removing someone from the workspace cuts off their clients immediately.
-   Workspace owners can rotate the API key in the app at any time.

See our [Privacy Policy](https://unifieddata.ai/privacy.md) for how your data is handled.

## Troubleshooting

Problem

Fix

The browser sign-in never opens

Make sure the client is set up for a remote **HTTP** server with OAuth, not a local command. If it cannot do OAuth, use the mcp-remote bridge or a workspace API key.

405 Method Not Allowed

The client tried the older HTTP+SSE transport. Choose Streamable HTTP in its settings, or use the mcp-remote bridge.

401 Unauthorized, or tools stop working after a while

Your sign-in expired or was revoked, or you were removed from the workspace. Re-authenticate in the client (for example `/mcp` in Claude Code, or disconnect and reconnect the connector).

“This token is missing the required scope”

The client was approved without that permission. Disconnect, reconnect and approve the scopes you want it to use.

A tool says you don’t have permission

Your workspace role is too low for that tool. See the Role column in the tool tables, or ask a workspace admin.

The client is working in the wrong workspace

The workspace is chosen when you approve the client. Disconnect, reconnect and pick the other workspace.

## For client developers

-   Management server: Streamable HTTP, `POST` only (other methods get `405`), stateless. Serves protocol revision 2026-07-28 (no `initialize` handshake) and earlier revisions back to 2025-03-26. Tools only; no resources or prompts.
-   Protected resource metadata (RFC 9728): `https://api.unifieddata.io/.well-known/oauth-protected-resource/data/mcp`
-   Authorization server metadata (RFC 8414): `https://api.unifieddata.io/.well-known/oauth-authorization-server`
-   Clients identify themselves with a Client ID Metadata Document (preferred) or Dynamic Client Registration at `https://api.unifieddata.io/oauth/register`. Redirect URIs must be HTTPS, or HTTP on a loopback address.
-   Authorization code with PKCE S256 (`plain` is refused) and refresh tokens. The `resource` parameter (RFC 8707) is required and must be the server URL. Public clients and client secrets are both supported; authorization responses include `iss` (RFC 9207). Revoke refresh tokens at `https://api.unifieddata.io/oauth/revoke`.
-   A `401` carries a `WWW-Authenticate` challenge naming the resource metadata and the product’s scopes. A client may request only the product’s own scopes; asking for none grants them all.

## Need help?

If you have trouble connecting, [contact us](https://unifieddata.ai/contact.md) or read the [FAQ](https://unifieddata.ai/faq.md).
