Server connections

Connect an MCP server

Changed on

Starts a connection request for an MCP server URL. Discovery, browser consent, and validation happen asynchronously; poll the returned connectionRequestId until the status is terminal. When the next step belongs to a person, the response carries a handoffUrl to open.

post/server-connections

Request

  • Base URL
    https://app.mcpjam.com/api/v1
  • URL
    https://app.mcpjam.com/api/v1/server-connections
  • Auth
    HTTP bearer

Request body

urlstring required

The MCP server URL to connect.

projectIdstring

Omit to have the user choose in the browser; a request with no project resolves to awaiting_project rather than defaulting to one.

serverIdstring

Disambiguates when a project already has several saved servers on this URL.

namestring

Used only if a server row is created. Ignored when an existing row is reused.

reauthorizeboolean

Skip deduplication and force a fresh authorization.

Response

Connection request created.

connectionRequestIdstring required

Public scr_… identifier. Safe to print; it is never sufficient to act on a request.

status'discovering' | 'awaiting_project' | 'awaiting_authorization' | 'authorizing' | 'validating' | 'ready' | 'failed' | 'expired' | 'cancelled' required
handoffUrlstring

Where the user finishes in a browser, for both awaiting_project and awaiting_authorization. Returned ONLY by the create call — the raw token behind it is minted once and never stored. Treat it as a private, single-person capability: never post it to a shared channel.

expiresAtstring date-time required
projectIdstring
serverIdstring

Changes