Skip to content
Docs
GitHub

Add an MCP server for the person

Preview

Add an MCP server for the person, from the catalog or by URL.

Public APIEverruns Cloud and self-hosted Platform

POST/v1/virtual-users/{identity_id}/mcp-servers

See authentication for credentials and permissions.

identity_id
required
string

me or a virtual user id

Media typeapplication/json

Add a user MCP server. Give catalog to add a catalog preset, or name and url to add a custom server.

object
api_key

API key for a custom api_key server. Never returned.

string | null
auth_mode
One of:

Sign-in for a custom server. Defaults to api_key when api_key is given, otherwise none.

string
Allowed values: none api_key oauth

Example

api_key
catalog

Catalog preset name to add.

string | null

Example

linear
deferred

Load the server’s tools on demand. Defaults to true.

boolean | null
description
string | null
enabled

Defaults to true.

boolean | null
headers

Literal headers for a custom server. Never returned.

object | null
name

Name for a custom server; also the tool prefix agents see.

string | null

Example

my-notes
url

HTTPS endpoint of a custom server.

string | null

Example

https://mcp.example.com/mcp

Responses

201Created

Created

Media typeapplication/json

An MCP server a person added for themselves.

object
auth_mode
required

MCP server authentication mode.

string
Allowed values: none api_key oauth
catalog_name

Catalog preset name, for servers added from the catalog.

string | null
connection
required

Sign-in state of a user MCP server.

object
connected_at
string | null format: date-time
provider

Connection provider to pass to the authorize endpoint (/v1/virtual-users/{id}/connections/{provider}/authorize) when the server signs in with OAuth.

string | null
status
required

Whether the person has signed in to a user MCP server.

string
Allowed values: connected not_connected not_needed
created_at
required
string format: date-time
deferred
required

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.

boolean
description
string | null
enabled
required

Disabled servers are kept but never offered to agents.

boolean
header_names

Names of the literal headers sent with each request. Values are write-only.

Array<string>
id
required
string
name
required
string
presentation
One of:

Title, icon, and links published by the remote server.

object
description
string | null
documentation_url
string | null
fetched_at
string | null format: date-time
icons
Array<object>
object
mime_type
string | null
sizes
Array<string>
src
required

https URL on the MCP server’s origin, or a raster data: URI.

string
theme
One of:
string
Allowed values: light dark
sources

Which documents contributed. Not shown in the UI.

Array<string>
title
string | null
version
string | null
website_url
string | null
source
required

Where a user MCP server came from.

string
Allowed values: catalog custom
updated_at
required
string format: date-time
url
required
string

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