---
title: "Core Unified API"
url: "https://docs.unified.to/mcp/core"
description: "The Unified MCP Server has two personalities:"
generated_at: "2026-07-14T20:29:19.757Z"
---
# Core Unified API

The Unified MCP Server has two personalities:

* **Connection mode** — point it at a single end-customer connection and it exposes that connection's integration-specific tools (CRM contacts, accounting invoices, HRIS employees, and so on).
* **Core Unified API mode** — authenticate with only a workspace API key (no connection ID) and it exposes the [Core Unified API](https://docs.unified.to/unified/overview) management tools for your **own** workspace configuration data.

This page covers Core Unified API mode.

> **Note:** Core Unified API mode operates on your workspace configuration data (connections, webhooks, integrations, API-call logs, issues, environments). It does **not** read or write your end-customers' data inside their connections — use a per-connection URL for that (see [get\_unified\_connection\_mcp\_url](#get%5Funified%5Fconnection%5Fmcp%5Furl)).

## [Authentication](#authentication)

Provide a Unified.to [workspace API key](https://app.unified.to/settings/api) as the only credential. This is the "Private Workspace-only Authentication" method described in [Authentication](https://docs.unified.to/mcp/authentication).

The `token` may be supplied either way:

| Location             | Example                                                  |
| -------------------- | -------------------------------------------------------- |
| URL parameter        | https://mcp-api.unified.to/mcp?token=<workspace-api-key> |
| Authorization header | Authorization: bearer <workspace-api-key>                |

All other options must be passed as URL parameters.

> **Warning:** A workspace API key grants access to **all** of your connections and your entire Unified.to account. Treat it as a secret and never expose it in a shareable URL. To hand out access to a single connection, generate a connection-scoped URL with [get\_unified\_connection\_mcp\_url](#get%5Funified%5Fconnection%5Fmcp%5Furl).

## [Endpoints](#endpoints)

| Transport        | US                             | EU                                |
| ---------------- | ------------------------------ | --------------------------------- |
| Streamable HTTP  | https://mcp-api.unified.to/mcp | https://mcp-api-eu.unified.to/mcp |
| SSE (deprecated) | https://mcp-api.unified.to/sse | https://mcp-api-eu.unified.to/sse |

### [Client configuration](#client-configuration)

Streamable HTTP:

```
{
  "mcpServers": {
    "unified-core": {
      "type": "streamable-http",
      "url": "https://mcp-api.unified.to/mcp?token=<workspace-api-key>"
    }
  }
}

```

Via `mcp-remote` (for clients that only speak stdio):

```
{
  "mcpServers": {
    "unified-core": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp-api.unified.to/mcp?token=<workspace-api-key>"]
    }
  }
}

```

## [Tools](#tools)

Core Unified API mode exposes the following tools.

### [Connections](#connections)

| Tool                               | Description                                                                                        |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
| list\_unified\_connections         | List the connections in your workspace                                                             |
| get\_unified\_connection           | Retrieve a single connection by ID                                                                 |
| create\_unified\_connection        | Create a connection                                                                                |
| update\_unified\_connection        | Update a connection                                                                                |
| remove\_unified\_connection        | Delete a connection                                                                                |
| get\_unified\_connection\_mcp\_url | Generate a connection-scoped MCP remote URL (see [below](#get%5Funified%5Fconnection%5Fmcp%5Furl)) |

### [Webhooks](#webhooks)

| Tool                              | Description              |
| --------------------------------- | ------------------------ |
| list\_unified\_webhooks           | List webhooks            |
| get\_unified\_webhook             | Retrieve a webhook by ID |
| create\_unified\_webhook          | Create a webhook         |
| update\_unified\_webhook          | Update a webhook         |
| remove\_unified\_webhook          | Delete a webhook         |
| update\_unified\_webhook\_trigger | Trigger a webhook        |

### [Integrations](#integrations)

| Tool                        | Description                                                      |
| --------------------------- | ---------------------------------------------------------------- |
| list\_unified\_integrations | List the available integrations and their supported capabilities |

### [Issues](#issues)

| Tool                  | Description                                         |
| --------------------- | --------------------------------------------------- |
| list\_unified\_issues | List issues / tickets raised against your workspace |
| get\_unified\_issue   | Retrieve a single issue by ID                       |

### [API calls](#api-calls)

| Tool                    | Description                          |
| ----------------------- | ------------------------------------ |
| list\_unified\_apicalls | List recent API-call logs            |
| get\_unified\_apicall   | Retrieve a single API-call log by ID |

### [Environments](#environments)

| Tool                         | Description                      |
| ---------------------------- | -------------------------------- |
| list\_unified\_environments  | List authentication environments |
| create\_unified\_environment | Create an environment            |
| remove\_unified\_environment | Delete an environment            |

## [get\_unified\_connection\_mcp\_url](#get%5Funified%5Fconnection%5Fmcp%5Furl)

This is the bridge from Core Unified API mode into connection mode: manage your connections with your workspace API key, then generate a ready-to-use MCP remote URL for any individual connection. The URL exposes that connection's integration-specific tools over both Streamable HTTP (`/mcp`) and SSE (`/sse`).

### [Parameters](#parameters)

| Parameter                | Required | Description                                                                                                        |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| connection\_id           | yes      | The ID of the connection to generate an MCP remote URL for                                                         |
| mode                     | no       | Authentication method for the generated URL — api (default) or user. See [Modes](#modes)                           |
| permissions              | no       | Comma-separated permission scopes to limit the tools the URL exposes (e.g. crm\_contact\_read,crm\_company\_read)  |
| tools                    | no       | Comma-separated tool IDs or wildcard patterns to limit which tools the URL exposes (e.g. list\_\*,\*invoices\*)    |
| aliases                  | no       | Custom description aliases (key:alt1,alt2;key2:alt3) to improve tool matching (e.g. employee:user;employees:users) |
| defer\_tools             | no       | Defer tool loading to reduce context usage — all or a comma-separated list of tool IDs                             |
| dc                       | no       | Preferred data center / region (us, eu, au, dev)                                                                   |
| hide\_sensitive          | no       | When true, strips PII and other sensitive fields from tool responses before they reach the LLM                     |
| include\_external\_tools | no       | When true, exposes the vendor's raw passthrough endpoints as additional callable MCP tools                         |

Any option supplied is baked into the returned URLs as a query parameter. See [Server options](https://docs.unified.to/mcp/server-options) for the full behavior of each one.

### [Modes](#modes)

The `mode` parameter selects the [authentication method](https://docs.unified.to/mcp/authentication) embedded in the generated URL:

| mode          | Generated URL                                             | Sharing                                                                                                                                                                          |
| ------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api (default) | …/mcp?connection=<connectionId>&token=<workspace-api-key> | Embeds your workspace API key — grants full-account access. **Do not share.** The key can instead be moved out of the URL and sent via the Authorization: bearer <token> header. |
| user          | …/mcp?token=<connectionId>-<nonce>-<signature>            | Uses a connection-scoped **signed** token. Safe to share — it grants access only to that single connection and never exposes your workspace API key.                             |

### [Response](#response)

```
{
  "connection_id": "682e20be9ca303793060370f",
  "integration_type": "hubspot",
  "mode": "user",
  "mcp_url": "https://mcp-api.unified.to/mcp?token=682e20be9ca303793060370f-<nonce>-<signature>",
  "sse_url": "https://mcp-api.unified.to/sse?token=682e20be9ca303793060370f-<nonce>-<signature>",
  "note": "USER mode: this URL uses a connection-scoped signed token. It is safe to share and grants access only to this single connection."
}

```

### [Example](#example)

Generate a shareable, read-only CRM URL for one connection by calling `get_unified_connection_mcp_url` with:

* `connection_id`: `682e20be9ca303793060370f`
* `mode`: `user`
* `permissions`: `crm_contact_read,crm_company_read`
* `hide_sensitive`: `true`

The returned `mcp_url` can be dropped straight into any MCP client and only exposes the read-only CRM tools for that connection, with PII stripped from responses.