API Award Unified.to Real-Time Unified API wins Best Business Software API at the 2026 API Awards
Unified.to
All articles

How To Install

·

Agent Builder connects to Unified MCP by adding a remote MCP server URL, then enabling only the tools your agent needs.

OpenAI is deprecating Agent Builder. OpenAI notified developers on 3 June 2026 and has scheduled shutdown for 30 November 2026; its migration guide points to the Agents SDK or ChatGPT Workspace Agents (OpenAI deprecations, checked 12 October 2026). For a new build, connect Unified MCP through the Agents SDK HostedMCPTool (see the Agents SDK section below) or the Responses API MCP tool (connecting OpenAI to your product). Steps 1 and 2 apply to every route; step 3 applies to Agent Builder until it shuts down.

1) Create your Unified MCP server URL

Use the Streamable HTTP endpoint:

  • US: https://mcp-api.unified.to/mcp
  • EU: https://mcp-api-eu.unified.to/mcp
  • AU: https://api-au.unified.to/mcp

A credential works only on its own region's host, so use the endpoint for your workspace's region.

Authentication (required)

  • Connection-scoped signed token
    Send it in the header as Authorization: Bearer {token}. Generate it with get_unified_connection_mcp_url (mode=user); it works for one connection only. Keep your workspace API key on your server. Unified Docs
  • connection
    The end-customer connection ID, added to the URL only where your setup needs it.
  • permissions
    A comma-delimited list of Unified scope permissions (example format shown in docs: hris_employee_read). Unified Docs
  • tools
    A comma-delimited list of MCP tool IDs (example formats shown in docs: get_messaging_message, list_messaging_message). Unified Docs
  • hide_sensitive=true
    Strips PII, such as names, emails and phone numbers, from tool results. Unified Docs

Optional:

Example URL (placeholder values)

https://mcp-api.unified.to/mcp
  ?connection=CONNECTION_ID
  &permissions=hris_employee_read
  &hide_sensitive=true
  &tools=get_messaging_message,list_messaging_message

The token goes in the Authorization: Bearer header, never in the URL. If you haven't selected tools yet, skip tools= and fetch the tool list first.

2) Fetch tool IDs (so tools= is exact)

Unified MCP provides tool discovery and execution endpoints:

  • GET /tools to list available tools (including the id field) Unified Docs
  • POST /tools/{id}/call to execute a specific tool Unified Docs

Call GET /tools on your region's MCP host:

  • send the same Authorization: Bearer header you use for /mcp (the endpoint returns 401 without it)

Workflow:

  1. Call GET /tools with the same Authorization header, connection and permissions you'll use in production.
  2. Copy the id values you want.
  3. Add them back into your MCP URL using &tools=id1,id2,....

3) Connect Unified MCP in OpenAI Agent Builder

Agent Builder is scheduled to shut down on 30 November 2026 (OpenAI deprecations, checked 12 October 2026). Until then, the flow is:

  1. Open your Agent Builder workflow and select your agent.
  2. Go to Tools and add an MCP server (remote/web MCP server).
  3. Paste your Unified /mcp URL with its scoping parameters and connect.
  4. Enable only the tools you want available to this agent.

OpenAI's Agent Builder docs don't document a header or authentication field for MCP servers (checked 9 October 2026). To supply the connection-scoped token, use the authorization field of the MCP tool in the Responses API or the Agents SDK HostedMCPTool (see the appendix). OpenAI doesn't store that value, so send it with every request. OpenAI docs

If your agent has write access (create/update/delete), pair this with an approval step in your workflow.

Why scoping matters (tool limits, cost, security)

Tool limits

Models perform better when the toolset is small and relevant. A connection carries only the tools its authorization allows (a HubSpot connection carried 69 on 12 October 2026), and narrowing further with permissions and tools is the default best practice. Unified Docs

Cost (OpenAI tokens + Unified API requests)

On the OpenAI side, the MCP tool is billed via tokens used when importing tool definitions and making tool calls, with no additional per-tool-call fee from OpenAI beyond token usage. OpenAI docs

On the Unified side, each MCP tool call counts as 1 API request on your Unified plan. Unified Docs

Security

Remote MCP servers can access and return sensitive data. Reduce risk by default:

  • use least-privilege permissions
  • restrict tools
  • enable hide_sensitive=true Unified Docs

Agents SDK: the route after Agent Builder

The Agents SDK is one of the two routes OpenAI's migration guide names. If you export your Agent Builder configuration to code, or start fresh in the SDK, the same Unified MCP server URL goes into a hosted MCP tool configuration.

import os
from agents import Agent, HostedMCPTool

agent = Agent(
  name="Unified-powered agent",
  tools=[
    HostedMCPTool(tool_config={
"type":"mcp",
"server_label":"unifiedMCP",
"server_url":"https://mcp-api.unified.to/mcp?connection=...&permissions=hris_employee_read&hide_sensitive=true&tools=get_messaging_message,list_messaging_message",
# Connection-scoped signed token: works for one connection only.
# Keep your workspace API key on your server.
"authorization": os.environ["UNIFIED_MCP_TOKEN"],
"require_approval":"never",
    })
  ],
)

The implementation stays the same across UI and SDK: connect Unified as a remote MCP server URL, send the connection-scoped token as a bearer token rather than in the URL, then scope down to the smallest set of permissions and tools your workflow requires.

Start your 30-day free trial

Book a demo

All articles