Pragence

MCP servers API

External MCP servers whose tools the assistant can call at question time. See the Live lookup guide. The router's own prefix is /api/mcp-servers and it is mounted under /api/v1, so the paths begin /api/v1/api/mcp-servers.

The server object

MCPServerResponse:

PropertyTypeDescription
iduuidServer id
namestringDisplay name
descriptionstring | nullDescription
transportstringstreamable_http or sse
urlstringEndpoint address; may contain ${VAR} placeholders
credentials_hintstring | nullMasked hint of the stored credential. The credential is never returned
enabledbooleanWhether the assistant may use it
last_validated_atdatetime | nullLast list-tools check
validation_errorstring | nullWhy the last check failed
tool_namesarray of stringTools found by the last check
created_atdatetimeCreated
auth_modestringshared or per_user
signed_inboolean | nullFor a per_user server: whether the caller has signed in. null for a shared server

Manage servers

Creating, updating, validating and deleting need an organization admin. Listing and reading need any member.

POST /api/v1/api/mcp-servers

Returns 201 with the server object. 400 with a message when the request is not valid.

PropertyTypeRequiredDescription
namestring*1 to 100 characters
urlstring*Endpoint address
transportstringstreamable_http (default) or sse
descriptionstringUp to 2000 characters
credentialsobjectheaders (for example {"Authorization": "Bearer ..."}) and url_secrets (values for ${VAR} placeholders in the address)
enabledbooleanDefault true
validate_connectionbooleanRun a list-tools check on save. Default true
auth_modestringshared (default) or per_user

GET /api/v1/api/mcp-servers

A list of server objects for the organization.

GET /api/v1/api/mcp-servers/{connection_id}

One server object, or 404.

PATCH /api/v1/api/mcp-servers/{connection_id}

Update name, url, transport, description, credentials, enabled; validate_connection (default false) re-runs the check. auth_mode cannot be changed.

POST /api/v1/api/mcp-servers/{connection_id}/validate

Run the list-tools check again and record the result. Returns the server object.

DELETE /api/v1/api/mcp-servers/{connection_id}

Returns 204.

Per-person sign-in

For servers with auth_mode: "per_user". Any member may call these for themselves.

POST /api/v1/api/mcp-servers/{connection_id}/sign-in

Body: return_to (a console path; default /manage/sources/live). Returns {"authorize_url": "..."}. Send the caller's browser there. 400 with a message when the server uses a shared credential, does not publish how to sign in, or refuses to register this deployment. 404 for an unknown server.

After the person approves, the server returns them to the callback, which redirects to return_to on the console with signed_in=<connection_id>, or with sign_in_error.

DELETE /api/v1/api/mcp-servers/{connection_id}/sign-in

Forget the caller's own sign-in to this server. Returns 204.

On this page