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.
| Header | Value |
|---|---|
Authorization | Complete project API key. |
Content-Type | application/json. |
Accept | application/json, text/event-stream. Both are required on POST requests. |
MCP-Protocol-Version | Negotiated 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.
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.
| Symptom | What to check |
|---|---|
401 | Missing or invalid project key. |
403 | Key does not have workflows.run for this workflow. |
400 | Invalid JSON-RPC or an unsupported protocol header. |
406 | POST’s Accept header must include both JSON and event streams. |
415 | Send Content-Type: application/json. |
429 | Back off; the request has reached a quota or rate limit. |
500 or missing tools | Check the server-definition output, tool names, input schemas, and workflow API logs. |
| Tool error content | Check 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.