Expose workflows over MCP
Connect an external MCP client to published Agent Studio workflows and verify tool discovery.
Connect an external Model Context Protocol (MCP) client to Agent Studio so it can discover published workflows as callable tools. This guide covers bearer-token authentication, session initialization, tool discovery, and a safe connection check.
Before you begin
You need a reachable Agent Studio base URL, permission to configure its environment, and at least one published workflow. You also need an MCP client that supports Streamable HTTP with a Server-Sent Events (SSE) stream and lets you send an Authorization header.
MCP_ACCESS_TOKEN as a secret. Store it in the client’s secret or environment configuration, never in source control or a shared client configuration file.Agent Studio also accepts an active Clerk session, but an external client normally uses the bearer token. If MCP_ACCESS_TOKEN is empty, only Clerk-authenticated requests are accepted.
Understand the connection
The client initializes a session with POST /api/mcp/sse. Agent Studio creates a tool for each workflow version that is currently published. The client then uses the returned MCP session ID for later messages and for the GET request that opens the SSE stream.
Connect the client
Set MCP_ACCESS_TOKEN in the Agent Studio runtime environment to a strong, randomly generated value. Restart or redeploy the application through your normal operational process so the runtime receives the new value.
The endpoint now accepts requests whose Authorization header contains that exact bearer token. Requests with no valid Clerk session and no matching token return HTTP 401.
In your MCP client, add a Streamable HTTP server that points to this URL, replacing the example origin with your Agent Studio origin:
https://studio.example.com/api/mcp/sseUse HTTPS outside a trusted local development environment. The configured endpoint handles both session messages and the SSE stream.
Configure the client to send the following header on both POST and GET requests:
Authorization: Bearer <MCP_ACCESS_TOKEN>Replace the placeholder through the client’s secret mechanism. Do not paste the token into logs, screenshots, or connection names.
Connect from the client. Its first POST request must be an MCP initialize request. Agent Studio creates a new session only for an initialization message and returns the session identifier through the MCP transport.
The client must preserve that identifier and send it as mcp-session-id on later requests. A non-initialization message without a known session returns HTTP 404 with an instruction to initialize first.
Allow the client to open GET /api/mcp/sse with the same bearer token and the issued mcp-session-id. A valid session produces the SSE response used for server-to-client messages.
If the client opens the stream without a known session ID, Agent Studio returns HTTP 404 instead of creating a session.
Open the client’s MCP tool list after the connection is active. Each currently published workflow is exposed as a tool with its description and input schema.
Run only a non-destructive published workflow with synthetic input for the first check. The result should appear in the client through the established MCP session.
Verify the connection
Publish or update workflows before establishing the session you want to test. Agent Studio builds a fresh tool list when it creates a session, so reconnect the client to discover workflows published after the current session began.
Troubleshoot the connection
Next steps
Use Manage MCP servers to configure MCP connections used by Agent Studio, or review the planned MCP and OpenAPI API reference for the HTTP surface.