MCP servers

Manage the MCP servers registered in the workspace — the tool providers agents attach to. To attach a server to a specific agent, see Agents. To talk to an agent as an MCP server, see Agent MCP.

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.

The MCP server object

PublicMcpServer:

Field	Type	Description
id	string	Server ID.
name	string	Display name.
transport	string	How the server is reached (e.g. `streamable-http`, `sse`, `stdio`).
url	string	Endpoint URL (remote transports).
headers	object	Headers sent with each request (remote transports).
command	string	Executable to run (local `stdio` transport).
args	array	Arguments for the command.
env	object	Environment variables for the command.
cwd	string	Working directory for the command.
force_serial_tool_calls	boolean	Run this server's tool calls one at a time.
oauth_client_config	object	OAuth client configuration attached to the server, with the client secret masked. `null` when the server doesn't use OAuth.

List MCP servers

GET /mcp-servers

Returns a PaginatedResponse of MCP servers.

Get an MCP server

GET /mcp-servers/{mcp_server_id}

Returns a single PublicMcpServer.

Create an MCP server

POST /mcp-servers

Registers a new MCP server. Provide the connection details for the server's transport — url/headers for a remote server, or command/args/env/cwd for a local one.

Body

Field	Type	Required	Description
name	string	Yes	Display name.
transport	string	No	`auto` (default), `streamable-http`, `sse`, or `stdio`.
url	string	No	Endpoint URL (remote).
headers	object	No	Request headers (remote).
command	string	No	Executable (local `stdio`).
args	array	No	Command arguments.
env	object	No	Command environment variables.
cwd	string	No	Command working directory.
force_serial_tool_calls	boolean	No	Serialize this server's tool calls.
type / icon / organization_type	string	No	Display and categorization metadata.
oauth_client_config	object	No	OAuth client configuration for servers that authenticate with OAuth 2.0.
validate_mcp_server	boolean	No	Validate the server configuration as part of the request (default `false`).

curl -X POST 'https://{your-deployment-host}/api/v2/mcp-servers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Weather",
    "transport": "streamable-http",
    "url": "https://mcp.example.com/weather"
  }'

Returns the created PublicMcpServer.

Update an MCP server

PUT /mcp-servers/{mcp_server_id}

Updates a server. Takes the same body as create (minus validate_mcp_server). Returns the updated PublicMcpServer.

OAuth client configuration

Servers that authenticate with OAuth 2.0 carry an oauth_client_config. Set it on create or update; reads return it with the client secret masked.

Field	Type	Required	Description
type	string	Yes	OAuth 2.0 flow — `oauth2-client-credentials` or `oauth2-authorization-code`.
dcr_enabled	boolean	Yes	Use Dynamic Client Registration.
resource_server_url	string	Yes	URL of the resource server the client is registered with.
client_id	string	No	OAuth 2.0 client ID.
client_secret	string	No	OAuth 2.0 client secret — write-only, see below.
scope	string	No	Space-separated OAuth 2.0 scopes.
token_endpoint	string	No	Token endpoint URL.
authorization_endpoint	string	No	Authorization endpoint URL (authorization-code flow only).
token_endpoint_auth_method	string	No	`client_secret_post`, `client_secret_basic`, or `none`. `none` is the public-client method (no secret, PKCE only) and is valid only for the authorization-code flow.

The client secret is write-only: responses always mask it as ********** (and null means no secret is stored). On update, sending the mask — or omitting the field — keeps the currently stored secret, so you can round-trip a read response without losing the secret. On create the mask is rejected. Responses name the flow field auth_type rather than type, and additionally include redirect_uri — the redirect URI registered with the provider when the configuration was created.

curl -X POST 'https://{your-deployment-host}/api/v2/mcp-servers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "CRM",
    "transport": "streamable-http",
    "url": "https://mcp.example.com/crm",
    "oauth_client_config": {
      "type": "oauth2-client-credentials",
      "dcr_enabled": false,
      "resource_server_url": "https://mcp.example.com/crm",
      "client_id": "my-client",
      "client_secret": "shhh",
      "token_endpoint": "https://auth.example.com/oauth/token"
    }
  }'

Delete an MCP server

DELETE /mcp-servers/{mcp_server_id}

Deletes a server. Returns 204 No Content.

Semantic data models LLMs