MCP and OpenAPI API reference
Manage MCP servers, discovery, protocol operations, compositions, and imported OpenAPI integrations.
Use these endpoints to register Model Context Protocol (MCP) servers, call their advanced capabilities, search integration directories, expose published workflows over MCP, and import REST operations from OpenAPI documents. Management routes require a signed-in session unless an endpoint states a separate token option.
MCP server model
Create operations accept SSE or STDIO transport. Names are 2–100 characters. An SSE server requires an HTTP or HTTPS endpointUrl of at most 2,000 characters; a STDIO server requires a command of 3–500 characters. headers can contain at most 20 string pairs.
List and create servers
/api/mcp/serversOrganization context; takes precedence.
Maximum results; capped at 200.
Organization context when the header is absent.
curl --request GET \ --url https://studio.example.com/api/mcp/servers?limit=25&organizationId=org_example \ --header 'X-Organization-Id: org_example'
{ "success": true, "data": [{ "id": "mcp_example", "name": "Research tools", "transport": "SSE" }] }/api/mcp/serversOptional organization context.
Server name.
`SSE` or `STDIO`.
Required for `SSE`.
Required for `STDIO`.
Up to 20 connection headers.
Connect after registration.
Organization context when the header is absent.
curl --request POST \
--url https://studio.example.com/api/mcp/servers \
--header 'Content-Type: application/json' \
--data '{
"name": "<string>",
"transport": "<string>",
"endpointUrl": "<string>",
"command": "<string>",
"headers": {},
"connectOnCreate": false,
"organizationId": "<string>"
}'{ "success": true, "data": { "id": "mcp_example", "status": "DISCONNECTED" } }curl -X POST 'https://studio.example.com/api/mcp/servers' \
-H 'Content-Type: application/json' \
--data '{"name":"Research tools","transport":"SSE","endpointUrl":"https://mcp.example.com/sse","connectOnCreate":false}'Read, update, and delete a server
/api/mcp/servers/:idServer ID.
curl --request GET \ --url https://studio.example.com/api/mcp/servers/:id
{ "success": true, "data": { "id": "mcp_example" } }/api/mcp/servers/:idServer ID.
Replacement name.
Replacement SSE URL.
Replacement STDIO command.
Replacement headers.
Remove stored headers.
curl --request PATCH \
--url https://studio.example.com/api/mcp/servers/:id \
--header 'Content-Type: application/json' \
--data '{
"name": "Research tools",
"endpointUrl": "https://mcp.example.com/sse",
"command": "npx example-mcp-server",
"headers": "\"X-Client\":\"agent-studio\"",
"clearHeaders": false
}'{ "success": true, "data": { "id": "mcp_example" } }/api/mcp/servers/:idServer ID.
curl --request DELETE \ --url https://studio.example.com/api/mcp/servers/:id
{ "success": true }Connection and discovery
/api/mcp/servers/:id/connectServer ID.
curl --request POST \ --url https://studio.example.com/api/mcp/servers/:id/connect
{ "success": true, "data": { "id": "mcp_example", "status": "CONNECTED" } }/api/mcp/servers/:id/disconnectServer ID.
curl --request POST \ --url https://studio.example.com/api/mcp/servers/:id/disconnect
{ "success": true, "data": { "status": "DISCONNECTED" } }/api/mcp/servers/:id/discoverConnected server ID.
curl --request POST \ --url https://studio.example.com/api/mcp/servers/:id/discover
{ "success": true, "data": { "id": "mcp_example", "cachedTools": [] } }/api/mcp/servers/:id/testConnected server ID.
Tool name.
Tool arguments; default: `{}`.
curl --request POST \
--url https://studio.example.com/api/mcp/servers/:id/test \
--header 'Content-Type: application/json' \
--data '{
"toolName": "search",
"arguments": "\"query\":\"release notes\""
}'{ "success": true, "data": { "content": [] } }Health, metrics, and progress
/api/mcp/servers/:id/healthServer ID.
curl --request GET \ --url https://studio.example.com/api/mcp/servers/:id/health
{ "success": true, "data": { "serverId": "mcp_example", "status": "available" } }/api/mcp/servers/:id/metricsServer ID.
curl --request GET \ --url https://studio.example.com/api/mcp/servers/:id/metrics
{ "success": true, "data": { "serverId": "mcp_example" } }/api/mcp/servers/:id/progressOwned server ID.
curl --request GET \ --url https://studio.example.com/api/mcp/servers/:id/progress
data: {"type":"connected","serverId":"mcp_example"}The progress stream sends heartbeat events every 30 seconds. An inaccessible or disconnected server receives no operational events after the initial connection event.
Resources and prompts
/api/mcp/servers/:id/resourcesConnected server ID.
curl --request GET \ --url https://studio.example.com/api/mcp/servers/:id/resources
{ "success": true, "data": [{ "uri": "docs://handbook" }] }/api/mcp/servers/:id/resources/readConnected server ID.
Nonempty resource URI from the list operation.
curl --request POST \
--url https://studio.example.com/api/mcp/servers/:id/resources/read \
--header 'Content-Type: application/json' \
--data '{
"uri": "file:///example/readme.md"
}'{ "success": true, "data": { "contents": [] } }/api/mcp/servers/:id/promptsConnected server ID.
curl --request GET \ --url https://studio.example.com/api/mcp/servers/:id/prompts
{ "success": true, "data": [{ "name": "summarize" }] }/api/mcp/servers/:id/promptsConnected server ID.
Prompt name.
Template arguments.
curl --request POST \
--url https://studio.example.com/api/mcp/servers/:id/prompts \
--header 'Content-Type: application/json' \
--data '{
"name": "summarize",
"arguments": "\"topic\":\"release notes\""
}'{ "success": true, "data": { "messages": [] } }Sampling
/api/mcp/servers/:id/samplingConnected server ID.
Messages with `user` or `assistant` role and a content object.
Optional system instruction.
Value from 0 through 2.
1–128,000. Default: 4,096.
Optional stop strings.
curl --request POST \
--url https://studio.example.com/api/mcp/servers/:id/sampling \
--header 'Content-Type: application/json' \
--data '{
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Summarize this update."
}
}
],
"systemPrompt": "Answer concisely.",
"temperature": 0.2,
"maxTokens": 4096,
"stopSequences": [
"END"
]
}'{ "success": true, "data": { "role": "assistant", "content": { "type": "text", "text": "Result" } } }Batch, import, and export
/api/mcp/servers/batch`connect`, `disconnect`, or `health`.
Targets; omit or send an empty array to target all personal servers.
curl --request POST \
--url https://studio.example.com/api/mcp/servers/batch \
--header 'Content-Type: application/json' \
--data '{
"action": "health",
"serverIds": [
"mcp_example"
]
}'{ "success": true, "data": [{ "id": "mcp_example", "ok": true }] }The batch response can have success: true while individual entries have ok: false; inspect every result.
/api/mcp/servers/exportcurl --request GET \ --url https://studio.example.com/api/mcp/servers/export
{ "version": "1", "servers": [] }/api/mcp/servers/importBundle version.
One or more server definitions with name, transport, connection location, optional headers, and optional connect preference.
curl --request POST \
--url https://studio.example.com/api/mcp/servers/import \
--header 'Content-Type: application/json' \
--data '{
"version": 1,
"servers": [
{
"name": "Research tools",
"transport": "SSE",
"endpointUrl": "https://mcp.example.com/sse"
}
]
}'{ "success": true, "data": { "importedCount": 1, "errorCount": 0, "servers": [] } }Imported servers never connect automatically, even when a bundle requests connectOnCreate. This prevents importing a bundle from immediately running an arbitrary STDIO command.
MCP directory
/api/mcp/directorySearch text.
Category or `ALL`.
Directory source or `ALL`.
Transport filter or `ALL`.
Implementation language or `ALL`.
curl --request GET \ --url https://studio.example.com/api/mcp/directory?q=research&category=ALL&source=ALL&transport=SSE&language=TypeScript
{ "success": true, "data": [] }/api/mcp/directory/githubGitHub repository URL.
curl --request GET \ --url https://studio.example.com/api/mcp/directory/github?repo=https%3A%2F%2Fgithub.com%2Fexample%2Fexample-mcp-server
{ "success": true, "data": { "repoUrl": "https://github.com/example/example" } }/api/mcp/directory/healthEndpoint to probe.
curl --request POST \
--url https://studio.example.com/api/mcp/directory/health \
--header 'Content-Type: application/json' \
--data '{
"endpointUrl": "https://mcp.example.com/sse"
}'{ "success": true, "reachable": true }/api/mcp/skills-feedSearch text.
Category or `ALL`.
Difficulty or `ALL`.
`ALL`, `glama`, `mcp.so`, `smithery`, or `composio`.
Page number; default: 1.
10–100; default: 50.
curl --request GET \ --url https://studio.example.com/api/mcp/skills-feed?q=research&category=ALL&difficulty=ALL&source=ALL&page=1&pageSize=50
{ "success": true, "data": [], "pagination": { "currentPage": 1 } }/api/mcp/presetscurl --request GET \ --url https://studio.example.com/api/mcp/presets
{ "success": true, "data": [] }Provider directories
/api/mcp/smithery`list` or `detail`. Default: `list`.
Required for `detail`.
Search text.
`servers` or `skills`. Default: `servers`.
Fetch all pages when `true`.
Default: 1.
Default: 50.
curl --request GET \ --url https://studio.example.com/api/mcp/smithery?action=list&qualifiedName=example%2Fserver&q=research&type=servers&fetchAll=false&page=1&pageSize=50
{ "success": true, "data": [], "pagination": { "currentPage": 1 } }/api/mcp/composiocurl --request GET \ --url https://studio.example.com/api/mcp/composio
{ "success": true, "data": [] }/api/mcp/composioToolkit slugs; omit for all.
Per-toolkit enabled tools.
curl --request POST \
--url https://studio.example.com/api/mcp/composio \
--header 'Content-Type: application/json' \
--data '{
"toolkits": [
"github"
],
"tools": "\"github\":[\"search_repositories\"]"
}'{ "success": true, "data": { "sessionId": "session_example", "mcpUrl": "https://mcp.example.com", "mcpHeaders": {} } }/api/mcp/arcadecurl --request GET \ --url https://studio.example.com/api/mcp/arcade
{ "success": true, "data": [] }/api/mcp/arcadeArcade integration slug.
curl --request POST \
--url https://studio.example.com/api/mcp/arcade \
--header 'Content-Type: application/json' \
--data '{
"integration": "github"
}'{ "success": true, "data": { "integration": "github", "mcpUrl": "https://mcp.arcade.dev/github", "verified": true } }The Arcade response can be successful with verified: false; connection details are still returned for a later explicit connection attempt.
Quality and updates
/api/mcp/qualityServer descriptors with ID and optional transport, endpoint, repository, description, stars, verification, and cached tool schemas.
curl --request POST \
--url https://studio.example.com/api/mcp/quality \
--header 'Content-Type: application/json' \
--data '{
"servers": [
{
"id": "mcp_example",
"transport": "SSE"
}
]
}'{ "success": true, "data": [{ "serverId": "mcp_example", "overallScore": 82 }] }STDIO servers and entries without an HTTP endpoint receive a neutral latency score rather than a measured probe. Quality output is advisory and does not establish persistent ratings or uptime guarantees.
/api/mcp/updatescurl --request GET \ --url https://studio.example.com/api/mcp/updates
{ "success": true, "data": [] }/api/mcp/updatesUpdate entry ID.
curl --request POST \
--url https://studio.example.com/api/mcp/updates \
--header 'Content-Type: application/json' \
--data '{
"updateId": "update_example"
}'{ "success": true, "data": { "updateId": "update_example" } }Compositions
/api/mcp/compositionsCase-insensitive search text.
curl --request GET \ --url https://studio.example.com/api/mcp/compositions?q=research
{ "success": true, "total": 1, "data": [] }/api/mcp/compositionsComposition name.
Description.
Composition nodes.
Composition edges.
Search tags.
curl --request POST \
--url https://studio.example.com/api/mcp/compositions \
--header 'Content-Type: application/json' \
--data '{
"name": "Research composition",
"description": "Search and summarize sources.",
"nodes": [
{
"id": "search"
}
],
"edges": [],
"tags": [
"research"
]
}'{ "success": true, "data": { "id": "composition_example" } }The route returns the created composition for the current process, but the source does not establish durable composition persistence. See Create MCP compositions for supported usage.
Agent Studio MCP protocol
These routes expose published Agent Studio workflows to an MCP client. They accept either a Clerk session or Authorization: Bearer <MCP_ACCESS_TOKEN> configured by the administrator.
/api/mcp/sseBearer MCP access token when no Clerk session is present.
curl --request GET \ --url https://studio.example.com/api/mcp/sse \ --header 'Authorization: Bearer mcp_example_token'
event: endpoint
/api/mcp/sseBearer MCP access token when no Clerk session is present.
Session identifier supplied by the transport when applicable.
MCP JSON-RPC request or notification.
curl --request POST \
--url https://studio.example.com/api/mcp/sse \
--header 'Authorization: Bearer mcp_example_token' \
--header 'mcp-session-id: session_example' \
--header 'Content-Type: application/json' \
--data '{
"JSON-RPC message": "\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\""
}'{ "jsonrpc": "2.0", "id": 1, "result": {} }/api/mcp/messagesBearer MCP access token when no Clerk session is present.
Session transport identifier.
MCP JSON-RPC request or notification.
curl --request POST \
--url https://studio.example.com/api/mcp/messages \
--header 'Authorization: Bearer mcp_example_token' \
--header 'mcp-session-id: session_example' \
--header 'Content-Type: application/json' \
--data '{
"JSON-RPC message": "\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\""
}'{ "jsonrpc": "2.0", "id": 2, "result": {} }OpenAPI directory and parsing
/api/openapi/directorySearch text.
Category filter.
Provider filter.
Page number; minimum 1 and default 1.
1–100; default 24.
curl --request GET \ --url https://studio.example.com/api/openapi/directory?q=tickets&category=support&provider=example&page=1&limit=24
{ "success": true, "data": [], "pagination": { "page": 1, "limit": 24 } }/api/openapi/parseDocument URL.
Raw document. Supply this or `specUrl`.
curl --request POST \
--url https://studio.example.com/api/openapi/parse \
--header 'Content-Type: application/json' \
--data '{
"specUrl": "https://api.example.com/openapi.json",
"rawSpec": "\"openapi\":\"3.0.0\",\"info\":{\"title\":\"Ticket API\",\"version\":\"1.0.0\"},\"paths\":{}"
}'{ "success": true, "data": { "endpoints": [] } }OpenAPI integrations
An endpoint definition contains id, operationId, HTTP method, path, summary, description, tags, parameters, optional request body and responses, and the booleans isWrite, requiresApproval, and enabled. Supported authentication types are NONE, BEARER, API_KEY, BASIC, and CUSTOM_HEADER.
/api/openapi/integrationsMaximum results; capped at 200.
curl --request GET \ --url https://studio.example.com/api/openapi/integrations?limit=25
{ "success": true, "data": [] }/api/openapi/integrations2–100 characters.
At most 500 characters.
Source document URL.
Raw document; default: `{}`.
Valid request base URL.
Supported auth type. Default: `NONE`.
Credentials or custom headers for the chosen auth type.
At least one normalized endpoint definition.
curl --request POST \
--url https://studio.example.com/api/openapi/integrations \
--header 'Content-Type: application/json' \
--data '{
"name": "Ticket API",
"description": "Manage support tickets.",
"specUrl": "https://api.example.com/openapi.json",
"rawSpec": "\"openapi\":\"3.0.0\"",
"baseUrl": "https://api.example.com",
"authType": "NONE",
"authConfig": {},
"endpoints": [
{
"operationId": "listTickets",
"method": "GET",
"path": "/tickets"
}
]
}'{ "success": true, "data": { "id": "openapi_example", "name": "Ticket API" } }/api/openapi/integrations/:idIntegration ID.
curl --request GET \ --url https://studio.example.com/api/openapi/integrations/:id
{ "success": true, "data": { "id": "openapi_example" } }/api/openapi/integrations/:idIntegration ID.
Updated name.
Updated description.
Updated base URL.
Updated auth type.
Updated credentials or headers.
Replacement endpoint selection.
curl --request PUT \
--url https://studio.example.com/api/openapi/integrations/:id \
--header 'Content-Type: application/json' \
--data '{
"name": "Ticket API",
"description": "Manage support tickets.",
"baseUrl": "https://api.example.com",
"authType": "NONE",
"authConfig": {},
"endpoints": [
{
"operationId": "listTickets",
"method": "GET",
"path": "/tickets"
}
]
}'{ "success": true, "data": { "id": "openapi_example" } }/api/openapi/integrations/:idIntegration ID.
curl --request DELETE \ --url https://studio.example.com/api/openapi/integrations/:id
{ "success": true }Test OpenAPI operations
/api/openapi/integrations/:id/testIntegration ID.
Selected operation ID.
Path, query, header, and body arguments; default: `{}`.
curl --request POST \
--url https://studio.example.com/api/openapi/integrations/:id/test \
--header 'Content-Type: application/json' \
--data '{
"operationId": "listTickets",
"arguments": "\"query\":{\"status\":\"open\"}"
}'{ "success": true, "data": { "status": 200 } }/api/openapi/test-rawNormalized endpoint definition.
Valid request base URL.
Supported auth type. Default: `NONE`.
Credentials or custom headers.
Operation arguments; default: `{}`.
curl --request POST \
--url https://studio.example.com/api/openapi/test-raw \
--header 'Content-Type: application/json' \
--data '{
"endpoint": "\"operationId\":\"listTickets\",\"method\":\"GET\",\"path\":\"/tickets\"",
"baseUrl": "https://api.example.com",
"authType": "NONE",
"authConfig": {},
"arguments": "\"query\":{\"status\":\"open\"}"
}'{ "success": true, "data": { "status": 200 } }