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

POST

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

curl --request POST \
  --url https://app.everruns.com/api/v1/virtual-users/example/mcp-servers \
  --header 'Content-Type: application/json' \
  --data '{ "api_key": "example", "auth_mode": "none", "catalog": "linear", "description": "example", "enabled": true, "headers": "example", "name": "my-notes", "url": "https://mcp.example.com/mcp" }'

• Production API

Parameters

Path Parameters

identity_id

required

string

me or a virtual user id

Request Body^required

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:

string

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

null

null

catalog

Catalog preset name to add.

string | null

Example

linear

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

201

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

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

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",
  "source": "catalog"
}

400

Invalid request

401

Authentication required

403

Permission denied

409

Name already used