Manage MCP servers

Decide whether the server belongs to your personal account or an organization. For a personal server, omit the organization context. For an organization server, send the organization ID in the X-Organization-Id header or as organizationId in the create body.

Organization membership is checked for listing and creation. Creation also requires mcp:create.

Choose SSE when Agent Studio connects to a network endpoint. Choose STDIO when it starts a local command. A server name must contain 2–100 characters.

const definition = {
  name: "Support tools",
  transport: "SSE",
  endpointUrl: "https://mcp.example.com/events",
  headers: { "X-Client": "agent-studio" },
  connectOnCreate: false
};

You can provide at most 20 string-valued headers. connectOnCreate is optional.

Create the server with POST /api/mcp/servers. This personal example uses the definition object from the preceding step:

const response = await fetch("/api/mcp/servers", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(definition)
});

const result = await response.json();
if (!response.ok || !result.success) {
  throw new Error(result.error ?? "MCP server creation failed");
}

const serverId = result.data.id;

A successful create returns HTTP 201, success: true, and the saved server under data. Keep data.id for inspection, updates, testing, and deletion.

For an organization server, add "X-Organization-Id": organizationId to the request headers. Agent Studio links the created definition to that organization.

Retrieve the server by ID to confirm its saved configuration:

const response = await fetch(`/api/mcp/servers/${serverId}`);
const result = await response.json();

if (!response.ok || !result.success) {
  throw new Error(result.error ?? "MCP server lookup failed");
}

To list personal servers, request GET /api/mcp/servers. Add ?limit=50 to restrict the result. Numeric limits are capped at 200.

To list organization servers, add the X-Organization-Id header or organizationId query parameter. The response contains the servers in data, ordered with the newest organization definitions first.

Send only the fields that need to change with PATCH /api/mcp/servers/:id. You can update name, endpointUrl, command, and headers, or set clearHeaders to remove saved headers.

const response = await fetch(`/api/mcp/servers/${serverId}`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Support tools staging",
    endpointUrl: "https://staging.mcp.example.com/events",
    clearHeaders: true
  })
});

const result = await response.json();
if (!response.ok || !result.success) {
  throw new Error(result.error ?? "MCP server update failed");
}

The request must contain at least one supported field. The update schema does not include transport; create a new definition when you need to switch between SSE and stdio.

Confirm that no workflow still depends on the definition, then delete it:

const response = await fetch(`/api/mcp/servers/${serverId}`, {
  method: "DELETE"
});
const result = await response.json();

if (!response.ok || !result.success) {
  throw new Error(result.error ?? "MCP server deletion failed");
}

A successful delete returns success: true. A later lookup for the same ID returns MCP server not found.