MCP Tool Connections
AI assistants can call tools from external Model Context Protocol (MCP) servers. A connection is not a separate resource: it is an item of the assistant's mcp_tools array. Use the connection test to check a server and read its tools, then save the connection on the assistant.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /mcp-tool-connection-proxy | Test an MCP connection |
PATCH | /ai-assistants/:id | Save connections on an assistant |
The MCP connection object
json
Fields
| Field | Type | Description |
|---|---|---|
url | string | Required. MCP server URL (Streamable HTTP). |
label | string | Required. Display name. |
description | string | null | What the server provides. |
authentication_type | string | Required. none, api_key, custom_headers or oauth2. |
api_key | string | null | Sent as Authorization: Bearer <api_key> when authentication_type is api_key. |
custom_headers | array | null | { key, value } headers sent when authentication_type is custom_headers. |
oauth2_config | object | null | For oauth2: authorization_server_url, client_id, client_secret, access_token, refresh_token, token_expiry, resource_uri, scopes. access_token is sent as a Bearer token. |
enabled_tools | string[] | null | Names of the tools the assistant may use. |
tools | array | null | Tool definitions returned by the server: name, description, inputSchema. |
needs_reauthorization | boolean | null | Set when the OAuth2 authorization must be renewed. |
Credentials are stored on the assistant and returned when you read it; treat assistant responses as sensitive.
Save a server on an assistant
mcp_tools replaces the whole array, so include every server the assistant should keep.
Related
Report an issue with this documentation
Please log in to report issues with our documentation.