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

MethodPathDescription
POST/mcp-tool-connection-proxyTest an MCP connection
PATCH/ai-assistants/:idSave connections on an assistant

The MCP connection object

json

Fields

FieldTypeDescription
urlstringRequired. MCP server URL (Streamable HTTP).
labelstringRequired. Display name.
descriptionstring | nullWhat the server provides.
authentication_typestringRequired. none, api_key, custom_headers or oauth2.
api_keystring | nullSent as Authorization: Bearer <api_key> when authentication_type is api_key.
custom_headersarray | null{ key, value } headers sent when authentication_type is custom_headers.
oauth2_configobject | nullFor 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_toolsstring[] | nullNames of the tools the assistant may use.
toolsarray | nullTool definitions returned by the server: name, description, inputSchema.
needs_reauthorizationboolean | nullSet 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.