A customer asks the online shop "Where is my Ember jacket?", and its AI agent step needs the order to answer. An MCP server is a service's endpoint, such as https://mcp.notion.com/mcp, that offers tools to AI models, such as searching a knowledge base or reading an order. An ai_agent step can call the tools of a remote server, as it calls http_request tools.
Heythere itself calls the server, whatever the step's AI provider, so every call appears in the workspace log and a tool declared as writes is never called twice for the same inputs.
How does a step use a server?
listMcpServerTools lists what a server offers. The step enables only the tools it needs, each an mcp tool naming the server's URL, the tool, and its input schema. The version a member publishes keeps that description. When the server later changes a tool, the step still calls it, and the log notes the change.
Who connects a server?
A server either needs no sign-in, or reads a token. The token comes from headers that read a secret, or from a connection a member makes once for the workspace by signing in to the service, on the MCP servers page of the console. The connection acts as that member's account at the service, stays when they leave the workspace, and is deleted on the same page. An agent never sees its tokens, only listMcpServerConnections.
What happens when a server is not connected?
getAutomation and replaceAutomationDraft return missingMcpServerConnections, with one console link connecting them all, which the agent gives the member. Testing or publishing such a draft fails with a conflict carrying the same link, and the Test pop-over offers to connect each server. A step whose connection was deleted, or whose server refused its tokens for good, tells its model the business has not connected the server, until a member connects it again.
In the API
Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. The OpenAPI document describes their parameters, payloads, and errors.
- GET
listMcpServerToolsList an MCP server's tools
/api/organizations/{organizationId}/workspaces/{workspaceId}/mcp-server-tools - GET
listMcpServerConnectionsList MCP server connections
/api/organizations/{organizationId}/workspaces/{workspaceId}/mcp-server-connections