Skip to main content

MCP Servers

Tags: ai, integrations, mcp

Model Context Protocol server management

In the product: Toolkits

Resources​

Request and response models used by the endpoints on this page.

McpServerResponse​

FieldTypeRequiredDescription
appUuidString
authMetadataDict[str, Any]
connectionTypeLiteral["mcp_server"]Default: mcp_server
createdAtDateTime✓
creatorIdInteger
creatorNameString
credentialIdInteger
descriptionString
enabledBoolean✓
iconUrlString
idInteger✓
lastConnectedAtDateTime
mcpUrlString✓
nameString✓
oauthClientIdString
permissionsIntegerDefault: 0
registrationUrlString
serverInstructionsString
serverNameString
serverVersionString
slugString✓
stateString✓
supportsDirectAuthBoolean✓
toolsArray
updatedAtDateTime✓
uuidString✓

Example:

{
  "connectionType": <AppConnectionType.MCP_SERVER: mcp_server  // Literal["mcp_server"], optional, default: mcp_server,
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "name": "string"  // String,
  "enabled": false  // Boolean,
  "creatorId": 0  // Integer, optional,
  "slug": "string"  // String,
  "description": "string"  // String, optional,
  "mcpUrl": "string"  // String,
  "appUuid": "string"  // String, optional,
  "credentialId": 0  // Integer, optional,
  "state": "string"  // String,
  "creatorName": "string"  // String, optional,
  "supportsDirectAuth": false  // Boolean,
  "serverName": "string"  // String, optional,
  "serverVersion": "string"  // String, optional,
  "serverInstructions": "string"  // String, optional,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "lastConnectedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "tools": []  // Array<McpToolResponse>, optional, default: PydanticUndefined,
  "permissions": 0  // Integer, optional, default: 0,
  "oauthClientId": "string"  // String, optional,
  "authMetadata": {}  // Dict[str, Any], optional,
  "registrationUrl": "string"  // String, optional,
  "iconUrl": "string"  // String, optional
}

McpToolResponse​

FieldTypeRequiredDescription
descriptionString
inputSchemaDict[str, Any]
nameString✓

Example:

{
  "name": "string"  // String,
  "description": "string"  // String, optional,
  "inputSchema": {}  // Dict[str, Any], optional
}

Endpoints​

List​

GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers

Description:

List all MCP servers the current member has access to.

Tools are NOT included in the list response. Use GET /app-connections/mcp-servers/{id}/tools to fetch tools for a specific server.

Authorization: Requires apps:read scope

Parameters:

  • sortBy (McpServerSortField)
  • sortOrder (SortOrder)

Response: List of McpServerResponse

Oauth Discovery​

POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/oauth-discovery

Description:

Discover OAuth metadata for a given server URL.

Authorization: Requires apps:write scope

Parameters:

Response: See OAuthDiscoveryResponse

Delete Server Id​

DELETE /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}

Description:

Delete an MCP server.

Authorization: Requires apps:admin scope

Parameters:

  • server_id (Integer)

Get Server Id​

GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}

Description:

Get a specific MCP server by ID.

Authorization: Requires apps:read scope

Parameters:

  • server_id (Integer)

Response: See McpServerResponse

Credentials​

POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/credentials

Description:

Create a MemberCredential linking the current member to an MCP server.

Used for direct_auth servers where no OAuth tokens are needed — simply establishes the member-to-app_connection link so the server recognises the member as authorised.

The (empty) JSON body is a deliberate CSRF barrier: authToken defaults to SameSite=None, so a bodyless POST is forgeable by a cross-site HTML form; requiring JSON forces cross-origin callers into CORS preflight. Platform-wide cookie-auth CSRF posture: GRA-6284.

Authorization: Requires apps:write scope

Parameters:

  • server_id (Integer)
  • _body (Object)

Disable​

POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/disable

Description:

Disable an MCP server.

Args: server_id: The MCP server ID clear_registration: If true, also clear OAuth registration info (client_id, secret, etc.)

Authorization: Requires apps:write scope

Parameters:

  • server_id (Integer)
  • clear_registration (Boolean)

Response: See McpServerResponse

Enable​

POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/enable

Description:

Enable an MCP server and test its connection.

This endpoint handles the state transitions:

  • READY + enabled -> return current state (already active)
  • READY + disabled -> re-enable and return
  • REGISTER -> try to connect or determine next setup step
  • AUTHORIZE -> error (user needs to complete OAuth flow)

Authorization: Requires apps:write scope

Parameters:

  • server_id (Integer)

Response: See McpServerResponse

Icon​

GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/icon

Description:

Get the favicon for an MCP server.

Token-authenticated (HMAC) so the endpoint can be embedded in <img src=...> for the web UI.

Authentication: Public endpoint (no authentication required)

Parameters:

  • server_id (Integer)
  • token (String)

Members​

GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/members

Description:

List all members who have connected to this MCP server.

Authorization: Requires apps:read scope

Parameters:

  • server_id (Integer)

Response: List of McpServerMemberResponse

Authorize​

GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/oauth/authorize

Description:

Initiate OAuth authorization flow for an MCP server.

This endpoint dynamically generates the OAuth authorization URL and redirects the client directly into the OAuth flow. The server must be in AUTH state. OAuth discovery and dynamic client registration may run when needed before redirecting.

Authorization: Requires apps:write scope

Parameters:

  • server_id (Integer)

Prompts​

GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/prompts

Description:

Get the prompts for an MCP server.

Returns 403 with a structured detail when the current user needs to authenticate before prompts can be fetched. OAuth tokens may be refreshed when connecting to the remote server.

Authorization: Requires apps:read scope

Parameters:

  • server_id (Integer)

Resources​

GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/resources

Description:

Get the resources for an MCP server.

Returns 403 with a structured detail when the current user needs to authenticate before resources can be fetched. OAuth tokens may be refreshed when connecting to the remote server.

Authorization: Requires apps:read scope

Parameters:

  • server_id (Integer)

Test​

POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/test

Description:

Test an MCP server connection by performing an initialize handshake.

A successful probe marks the server as ready and enabled. Returns success or failure with latency info.

Authorization: Requires apps:read scope

Parameters:

  • server_id (Integer)

Tools​

GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/tools

Description:

Get the tools for an MCP server.

Returns 403 with a structured detail when the current user needs to authenticate before tools can be fetched. The detail object contains code, authType and either authorizeUrl or appUuid so any client can prompt the user accordingly.

OAuth tokens may be refreshed and tool definitions are fetched from the remote MCP server when listing tools.

Authorization: Requires apps:read scope

Parameters:

  • server_id (Integer)