Skip to content
Try for free
On this page

MCP servers

List MCP servers

List external MCP servers registered in the workspace. Request-header values and OAuth secrets are omitted. Connection metadata remains at registration defaults until List MCP server tools performs discovery. Requires workspace read access. OAuth scope: `api:read`.

GET/api/v2/mcp-servers

List external MCP servers registered in the workspace. Request-header values and OAuth secrets are omitted. Connection metadata remains at registration defaults until List MCP server tools performs discovery. Requires workspace read access.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Query parameters

workspaceIdstringRequired

Workspace that owns the MCP server.

minLength
1
maxLength
128
searchstring

Case-insensitive substring match against the server name.

minLength
1
maxLength
200
sortBystring

Field used to sort the result. Do not rely on case-insensitive ordering when sorting by name.

default
createdAt
enum
["name","createdAt","updatedAt"]
sortOrderstring

Sort direction.

default
desc
enum
["asc","desc"]
limitinteger

Maximum MCP servers to return per page. Must be a whole number from 1 to 100. Defaults to 50.

default
50
minimum
1
maximum
100
cursorstring

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

minLength
1

Responses

200

MCP servers registered in the workspace.

object

MCP servers registered in the workspace.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

Public MCP server configuration without write-only credential values.

20 fields
idstringRequired

Unique server identifier derived from the workspace and endpoint URL.

namestringRequired

Server display name.

descriptionstring

Optional server description.

transportstringRequired

Transport used to communicate with the server.

default
streamable-http
enum
["streamable-http"]
authTypestring

Authentication method used by the server.

enum
["none","headers","oauth"]
urlstring

Server endpoint URL.

timeoutnumber

Per-request timeout in milliseconds.

retriesnumber

Number of retries attempted per request.

enabledbooleanRequired

Whether the server tools are available to workflows.

connectionStatusstring

Result of the most recent tool connection attempt. New registrations start disconnected; re-registration resets this state only when connection inputs change. Authentication probes do not establish a tool connection. Tool discovery updates this state.

enum
["connected","disconnected","error"]
lastErrorvalue

Message from the most recent failed tool connection, or null when absent. Successful discovery or re-registration with changed connection inputs clears it.

Schema details

Any of

Option 1string
Option 2null
toolCountnumber

Number of tools discovered on the server.

lastToolsRefreshstring

ISO 8601 timestamp of the most recent tool-list refresh.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
lastConnectedstring

ISO 8601 timestamp of the most recent successful tool connection. Absent until one succeeds, or after re-registration changes connection inputs.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
createdAtstringRequired

ISO 8601 timestamp when the server was registered.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAtstringRequired

ISO 8601 timestamp when the server was last updated.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
oauthClientIdstring

Pre-registered OAuth client identifier, when configured.

hasHeadersbooleanRequired

Whether any request headers are configured.

headerNamesarrayRequired

Names of configured request headers. Header values are never returned.

Schema details
Array itemstring

Configured header name.

hasOauthClientSecretbooleanRequired

Whether an OAuth client secret is stored. The value is never returned.

Additional properties are not allowed.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Response example 1

json
{
  "data": [
    {
      "id": "mcp-3f7a9c21",
      "name": "Docs server",
      "description": "Internal documentation tools",
      "transport": "streamable-http",
      "authType": "headers",
      "url": "https://mcp.example.com/sse",
      "timeout": 30000,
      "retries": 3,
      "enabled": true,
      "connectionStatus": "connected",
      "lastError": null,
      "toolCount": 7,
      "lastToolsRefresh": "2026-06-20T14:02:11.000Z",
      "lastConnected": "2026-06-20T14:02:11.000Z",
      "createdAt": "2026-06-01T09:14:00.000Z",
      "updatedAt": "2026-06-20T14:02:11.000Z",
      "hasHeaders": true,
      "headerNames": [
        "Authorization"
      ],
      "hasOauthClientSecret": false
    }
  ],
  "nextCursor": null
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit