Add an MCP server for the person
PreviewAdd an MCP server for the person, from the catalog or by URL.
/v1/virtual-users/{identity_id}/mcp-serversSee authentication for credentials and permissions.
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”me or a virtual user id
Request Bodyrequired
Section titled “Request Bodyrequired”Add a user MCP server. Give catalog to add a catalog preset, or name
and url to add a custom server.
object
API key for a custom api_key server. Never returned.
Catalog preset name to add.
Example
linearLoad the server’s tools on demand. Defaults to true.
Defaults to true.
Literal headers for a custom server. Never returned.
Name for a custom server; also the tool prefix agents see.
Example
my-notesHTTPS endpoint of a custom server.
Example
https://mcp.example.com/mcpResponses
201Created
Created
An MCP server a person added for themselves.
object
MCP server authentication mode.
Catalog preset name, for servers added from the catalog.
Sign-in state of a user MCP server.
object
Connection provider to pass to the authorize endpoint
(/v1/virtual-users/{id}/connections/{provider}/authorize) when the
server signs in with OAuth.
Whether the person has signed in to a user MCP server.
Whether the server loads on demand: agents see one line for it and list its tools only once they search for them. Off lists its tools from the start of every turn.
Disabled servers are kept but never offered to agents.
Names of the literal headers sent with each request. Values are write-only.
Title, icon, and links published by the remote server.
object
Which documents contributed. Not shown in the UI.
Where a user MCP server came from.
Example
{ "auth_mode": "none", "connection": { "status": "connected" }, "id": "mcp_01933b5a00007000800000000000001", "presentation": { "icons": [ { "theme": "light" } ], "title": "GitHub MCP Server", "website_url": "https://github.com" }, "source": "catalog"}400Invalid request
Invalid request
401Authentication required
Authentication required
403Permission denied
Permission denied
409Name already used
Name already used