Create MCP compositions
Define and validate a named multi-stage MCP composition with explicit nodes and directed edges.
Create a named MCP composition that describes how input moves through one or more MCP servers to an output. The composition endpoint returns a normalized graph descriptor; it does not execute the workflow or persist a submitted composition.
Before you begin
You must be signed in and know the IDs of the MCP servers you want to reference. Configure and test each server first with Manage MCP servers and Connect and test MCP tools.
Plan a directed path with unique node IDs. Each edge refers to its source and target by node ID, so a typo can leave a stage disconnected. The create route requires a non-empty name and arrays named nodes and edges; include meaningful node configuration because the route does not deeply validate the graph structure.
Model the workflow
The following pattern accepts a support question, asks one server to retrieve documentation, asks another to locate related tickets, and then produces an output.
The arrows are the composition's edges. They establish ordering between INPUT, MCP_SERVER, and OUTPUT nodes; they do not prove that the referenced servers are connected or compatible.
Create the composition
Select the smallest set of tested MCP servers that completes the job. Record each server ID from its Agent Studio server definition, and decide what each stage contributes.
For this example, server_docs retrieves product guidance and server_tickets retrieves related support history. Replace these placeholders with IDs owned by your account.
Create an INPUT node, one MCP_SERVER node per server, and an OUTPUT node. Give every node a unique id, a readable label, a config object, and a position for graph presentation. MCP server nodes also need the relevant serverId.
Keep secrets out of config. Store credentials in the server configuration rather than embedding them in the composition request.
Add an edge for every intended transition. Each edge needs its own id, plus a source and target that exactly match node IDs.
For a linear workflow, connect input to the first server, each server to the next, and the final server to output. Review the chain for missing nodes, accidental self-links, and unintended branches before submitting it.
Send the following JSON to POST /api/mcp/compositions through an authenticated Agent Studio session:
{
"name": "Support research pipeline",
"description": "Find relevant documentation and related support tickets.",
"tags": ["support", "research"],
"nodes": [
{"id": "input", "type": "INPUT", "label": "Question", "config": {"prompt": "Support question"}, "position": {"x": 50, "y": 100}},
{"id": "docs", "type": "MCP_SERVER", "label": "Documentation", "serverId": "server_docs", "config": {}, "position": {"x": 250, "y": 100}},
{"id": "tickets", "type": "MCP_SERVER", "label": "Tickets", "serverId": "server_tickets", "config": {}, "position": {"x": 450, "y": 100}},
{"id": "output", "type": "OUTPUT", "label": "Result", "config": {"format": "result"}, "position": {"x": 650, "y": 100}}
],
"edges": [
{"id": "e-input-docs", "source": "input", "target": "docs"},
{"id": "e-docs-tickets", "source": "docs", "target": "tickets"},
{"id": "e-tickets-output", "source": "tickets", "target": "output"}
]
}A successful response returns success: true and a composition in data. Agent Studio assigns an ID, creation and update timestamps, isPublished: false, usedBy: 0, and rating: 0.
Check the returned node and edge arrays against your intended path, then save the request JSON in your own controlled configuration repository if you need to recreate it.
GET /api/mcp/compositions returns freshly derived catalog templates, not compositions previously sent to POST. Usage and rating values are also not persisted.Verify the result
INPUT node to the OUTPUT node and verify that each MCP_SERVER node references the intended tested server ID.Troubleshooting
Next, expose workflows over MCP when you need external MCP clients to access an Agent Studio workflow.