Unified.to
All articles

How To Install

December 16, 2025

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

This is the fastest path to give OpenAI agents real-time access to customer systems through Unified connections, without building one-off function calls for each SaaS API.

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://mcp-api-au.unified.to/mcp

Required parameters

  • token
    Your Unified workspace API key (private), or an end-user-safe token for a single connection.
  • connection
    The end-customer connection ID (commonly used when token is a workspace API key).

Tokens can be passed as:

  • a token= URL parameter, or
  • Authorization: bearer {token} Unified Docs
  • 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
    Removes sensitive fields from results. Unified Docs

Optional:

Example URL (placeholder values)

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

If you haven't selected tools yet, skip tools= and fetch the tool list first.

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

Unified exposes 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

In practice, the Tools endpoint sits under the MCP base URL. For Streamable HTTP, that means:

  • GET https://mcp-api.unified.to/mcp/tools?... (requires auth; the endpoint returns 401 if you hit it without a token)

Workflow:

  1. Call GET /mcp/tools using the same token, 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's UI evolves quickly (beta), but the flow is consistent:

  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 and connect.
  4. Enable only the tools you want available to this agent.

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. Unified MCP can expose a very large catalog, so narrowing by 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 Platform+1

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

Appendix: what Code Export will look like (Agents SDK)

If you export your Agent Builder configuration to code, the same MCP server URL typically appears as a hosted MCP tool configuration.

from agentsimport 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?token=...&connection=...&permissions=hris_employee_read&hide_sensitive=true&tools=get_messaging_message,list_messaging_message",
"require_approval":"never",
    })
  ],
)

The implementation stays the same across UI and SDK: connect Unified as a remote MCP server 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