--- name: unified-mcp-core description: >- Use the Unified.to Core MCP server (workspace mode) to manage a Unified.to workspace from an AI agent: list and inspect connections, integrations, webhooks, API-call logs, issues and environments, search the docs, and mint connection-scoped MCP URLs. Use when tools such as `list_unified_connections`, `list_unified_apicalls` or `get_unified_connection_mcp_url` are available, or when a developer asks to connect Claude Code / Cursor / Codex / VS Code to their Unified.to workspace, check what is configured, debug a connection or webhook from the agent, or hand out MCP access to a single connection. license: MIT metadata: category: mcp mcp_url: https://mcp-api.unified.to/mcp docs: https://docs.unified.to/mcp/core docs_index: https://docs.unified.to/llms.txt --- # Use the Unified.to Core MCP server (workspace mode) The Unified MCP server has two personalities, chosen by the credential: | Mode | Credential | Tools | | ---------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------ | | **Core (workspace) mode** | workspace API key, **no** `connection` | Workspace management: connections, webhooks, integrations, logs, docs | | **Connection mode** | workspace API key + `connection`, or a signed token | One end-customer connection's data tools (CRM contacts, ATS jobs, …) | This skill covers **Core mode**. It operates on the developer's own workspace **configuration** (connections, webhooks, integrations, API-call logs, issues, environments) — it does **not** read or write end-customer data inside a connection. For that, mint a connection URL with `get_unified_connection_mcp_url` and follow the `unified-mcp-connection` skill (https://docs.unified.to/skills/unified-mcp-connection/SKILL.md). Source of truth: https://docs.unified.to/mcp/core. If anything here disagrees with the docs, or with the tool schemas the server actually returns, trust those and call `search_docs`. ## Step 1: Is the server connected? Look for tools named `search_docs`, `list_unified_connections`, `list_unified_integrations`, `list_unified_apicalls` (some clients prefix them, e.g. `mcp__unified-core__list_unified_connections`). If they exist, skip to Step 2. If not, help the developer add it. Ask which **region** the workspace lives in — a credential only resolves on its own region's host, anything else returns "not found": | Region | Endpoint (Streamable HTTP) | | ------ | ----------------------------------- | | US | `https://mcp-api.unified.to/mcp` | | EU | `https://mcp-api-eu.unified.to/mcp` | | AU | `https://api-au.unified.to/mcp` | The developer gets the workspace API key at https://app.unified.to/settings/api. With no account yet, the agent can create one itself: `POST https://api.unified.to/agent/signup` returns a workspace API key, the MCP URL and a claim link for the developer (https://docs.unified.to/mcp/agent-signup). Send it as `Authorization: Bearer `; read it from an environment variable (`UNIFIED_API_KEY`) so it never lands in a committed file. `?token=` in the URL still works but is deprecated (responses carry `Deprecation: true`). SSE (`/sse`) has been removed and returns `410` — change it to `/mcp`. **Claude Code** — the plugin bundles this server with every Unified.to skill and stores the key in secure storage: ``` /plugin marketplace add https://docs.unified.to/.claude-plugin/marketplace.json /plugin install unified@unified-to ``` Or just the server: ```bash claude mcp add --transport http unified-core https://mcp-api.unified.to/mcp \ --header "Authorization: Bearer $UNIFIED_API_KEY" ``` **Codex** ```bash codex mcp add unified-core --url https://mcp-api.unified.to/mcp --bearer-token-env-var UNIFIED_API_KEY ``` **Cursor** (`.cursor/mcp.json` or `~/.cursor/mcp.json`) ```json { "mcpServers": { "unified-core": { "url": "https://mcp-api.unified.to/mcp", "headers": { "Authorization": "Bearer ${env:UNIFIED_API_KEY}" } } } } ``` **VS Code** (`.vscode/mcp.json`) — prompts for the key on first start: ```json { "inputs": [ { "type": "promptString", "id": "unified-api-key", "description": "Unified.to workspace API key", "password": true } ], "servers": { "unified-core": { "type": "http", "url": "https://mcp-api.unified.to/mcp", "headers": { "Authorization": "Bearer ${input:unified-api-key}" } } } } ``` **stdio-only clients** — wrap it with `mcp-remote`: ```json { "mcpServers": { "unified-core": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp-api.unified.to/mcp", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer " } } } } ``` Most clients need a restart (or `/mcp` reconnect) before the tools appear. ## Step 2: The tools | Area | Tools | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Docs | `search_docs`, `list_unified_skills`, `get_unified_skill` | | Connections | `list_unified_connections`, `get_unified_connection`, `create_unified_connection`, `update_unified_connection`, `remove_unified_connection`, `get_unified_connection_mcp_url` | | Webhooks | `list_unified_webhooks`, `get_unified_webhook`, `create_unified_webhook`, `update_unified_webhook`, `remove_unified_webhook`, `update_unified_webhook_trigger` | | Integrations | `list_unified_integrations` | | Issues | `list_unified_issues`, `get_unified_issue` | | API calls | `list_unified_apicalls`, `get_unified_apicall` | | Environments | `list_unified_environments`, `create_unified_environment`, `remove_unified_environment` | The server may expose more than this list (for example connection re-authorization or secrets-manager tools). Read the schemas your client loaded rather than assuming parameters. Useful filters (check the schema before relying on them): - `list_unified_connections`: `categories`, `env`, `external_xref` (your own user/account ID stored on the connection), `updated_gte`, `limit`/`offset`. - `list_unified_integrations`: `active: true` for what the workspace has activated, `env` (`Sandbox` / `Production`), `categories`, `type`, `summary: true` for a compact list. - `list_unified_apicalls`: `connection_id`, `webhook_id`, `error: true`, `type` (`login`, `webhook`, `inbound`, `mcp`), `integration_type`, `updated_gte`. Logs are kept for 60 days. - `create_unified_webhook`: requires `connection_id`, `object_type` (e.g. `crm_contact`) and `event` (`created` / `updated` / `deleted`), plus `hook_url`; `webhook_type` is `native` or `virtual` (`interval` in minutes for virtual). `is_healthy` is read-only — an unhealthy webhook cannot be reset, only recreated. ## Step 3: Rules for acting on a workspace These tools change a real account. Follow them every time: 1. **Read before you write.** Start with `list_*` / `get_*`. Summarize what you found before proposing a change. 2. **Confirm destructive or outward-facing calls.** Ask the developer before any `remove_*`, before `update_unified_connection` (it can break a live customer integration), before `create_unified_webhook` (it starts delivering data to a URL) and before `update_unified_webhook_trigger`. 3. **Mind the environment.** Sandbox and Production are separate; pass `env` and say which one you looked at. 4. **Never print secrets.** Connection records can contain tokens and credentials, and `mode: "api"` MCP URLs embed the workspace API key. Don't echo them into chat, code, logs or commits; refer to IDs instead. 5. **Use `search_docs` instead of guessing** about object shapes, integration support or error meanings. ## Common workflows **"What's set up in my workspace?"** `list_unified_integrations` (`active: true`) for each env → `list_unified_connections` → `list_unified_webhooks`. Report counts per integration, unhealthy connections, and unhealthy or paused webhooks. **"Why is customer X's integration failing?"** 1. Find the connection: `list_unified_connections` with `external_xref`, or ask for the connection ID. `get_unified_connection` for its health and permissions. 2. `list_unified_apicalls` with `connection_id` and `error: true`; open the latest with `get_unified_apicall` and read the status code and message. 3. 401/403 → credentials or scopes; the end-user must re-authorize. 429 → provider rate limit. 404 → wrong ID or object not supported; check `list_unified_integrations` for that integration's support. 5xx → provider outage, usually transient. 4. Check `list_unified_issues` for an open ticket on it. For deeper guidance load https://docs.unified.to/skills/unified-debug-webhooks-connections/SKILL.md. **"Set up a webhook for new CRM contacts"** Confirm the connection, object, event, target URL and env with the developer, then `create_unified_webhook`. Verify with `get_unified_webhook` and, after the first run, `list_unified_apicalls` with `webhook_id`. **"Give my agent / my customer MCP access to one connection"** Call `get_unified_connection_mcp_url`: | Parameter | Purpose | | ------------------------ | ----------------------------------------------------------------------------- | | `connection_id` | Required | | `mode` | `api` (default) embeds the workspace key — **never share**. `user` mints a connection-scoped signed token — safe to share, revoked by deleting the connection | | `permissions` | Limit tools by scope, e.g. `crm_contact_read,crm_company_read` | | `tools` | Limit by tool ID or wildcard, e.g. `list_*,*invoice*` | | `hide_sensitive` | `true` strips PII from tool responses | | `defer_tools` | `all` or tool IDs, to save context | | `aliases` | Extra wording for tool matching, e.g. `employee:user;employees:users` | | `include_external_tools` | `true` adds the vendor's raw passthrough endpoints as tools | Default to `mode: "user"` whenever the URL leaves the developer's own servers, and to the narrowest `permissions` / `tools` the use case allows — many LLMs degrade with more than 20–50 tools. Read `mcp_url` from the response (there is no `sse_url` any more). The URL does not expire on its own; treat it as a secret. Then hand over to the `unified-mcp-connection` skill. ## Related skills - Connection-mode MCP: https://docs.unified.to/skills/unified-mcp-connection/SKILL.md - Getting started: https://docs.unified.to/skills/unified-quickstart/SKILL.md - Debugging: https://docs.unified.to/skills/unified-debug-webhooks-connections/SKILL.md - REST fundamentals: https://docs.unified.to/skills/unified-api/SKILL.md