Skip to main content

MCP server endpoint

Use this endpoint with a workflow configured as an MCP server.

POST /projects/:projectid/workflows/:workflowid/mcp

The same URL is used for initialization, notifications, tool discovery, and tool calls. Although the route accepts other HTTP methods for transport handling, POST is how clients send these protocol messages. This is not the older HTTP+SSE transport with separate event and message URLs.

Authentication and headers​

Requires workflows.run permission for the workflow. Send the project key on every request, without a Bearer prefix.

HeaderValue
AuthorizationComplete project API key.
Content-Typeapplication/json.
Acceptapplication/json, text/event-stream. Both are required on POST requests.
MCP-Protocol-VersionNegotiated protocol value on requests after initialization.

The endpoint does not issue an Mcp-Session-Id; no session ID needs to be saved or sent. Prefer an MCP client that handles initialization, notifications, protocol headers, and event-stream parsing for you.

Initialize​

Use the environment variables from the quickstart, and set INTELLECTIBLE_WORKFLOW_ID to your MCP workflow ID. This diagnostic example proposes a supported MCP protocol value:

curl --include --no-buffer --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json, text/event-stream" \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "example-client",
"version": "1.0.0"
}
}
}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/workflows/${INTELLECTIBLE_WORKFLOW_ID}/mcp"

Read result.protocolVersion from the initialization result and use that value in subsequent MCP-Protocol-Version headers. The result also contains server information and capabilities. It is normally delivered inside an SSE data: event, not as a standalone JSON response body.

Next, send an initialized notification to the same URL, with the same authentication and content headers plus the negotiated protocol header:

{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}

An accepted notification returns 202 Accepted with no body. It has no JSON-RPC id.

Discover tools​

Send this request to the same endpoint, using the headers described above:

{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}

The response’s result.tools array describes the workflow’s registered tools. For example, the JSON-RPC message carried by an SSE event might be:

{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"name": "find_customer",
"title": "Find customer",
"description": "Find a customer by email.",
"inputSchema": {
"type": "object",
"properties": {
"email": {
"type": "string"
}
},
"required": [
"email"
]
}
}
]
}
}

Tool names and schemas come from your workflow, so this example tool is not built in.

Call a tool​

Use a tool name returned by discovery. Supply its named arguments in params.arguments:

{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "find_customer",
"arguments": {
"email": "ada@example.com"
}
}
}

Arguments become workflow inputs. The matching MCP Server Tool Call Event starts the tool’s logic, and Set MCP Output supplies its result.

Example response message:

{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "{\"customer_name\":\"Ada\",\"status\":\"active\"}"
}
]
}
}

Return text or a JSON-serializable object from the workflow. Objects are serialized into the text content, so a client expecting an object must parse that text separately. This endpoint does not return the normal workflow API’s run-status envelope or a run ID for polling.

Tool calls can change data

A successful connection or tool listing does not mean every tool is read-only. Check the tool’s purpose before calling it. Retrying a tool call after a lost response can repeat its effects.

Responses and troubleshooting​

Request responses normally use 200 OK with text/event-stream. Parse the JSON-RPC message in each SSE data: event; do not call response.json() on the entire stream. Notifications can return 202 without content.

Check both the HTTP result and the MCP result. Protocol failures can contain a JSON-RPC error; a tool execution failure can instead return result.isError: true with an explanation in its content, even when HTTP succeeded.

SymptomWhat to check
401Missing or invalid project key.
403Key does not have workflows.run for this workflow.
400Invalid JSON-RPC or an unsupported protocol header.
406POST’s Accept header must include both JSON and event streams.
415Send Content-Type: application/json.
429Back off; the request has reached a quota or rate limit.
500 or missing toolsCheck the server-definition output, tool names, input schemas, and workflow API logs.
Tool error contentCheck argument values and the tool’s execution path in the workflow.

Initialization and discovery execute the workflow’s server-definition path, so that path must produce valid configuration. Tool calls must produce an output; finishing without one is not a successful tool response. See Logs and troubleshooting and Errors, limits and retries.