MCP Servers

Tags: ai, integrations, mcp

Model Context Protocol server management

In the product: App Connections

Resources

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

McpServerMemberResponse

Field	Type	Required	Description
connectedAt	DateTime
externalEmail	String
externalUsername	String
memberId	Integer	✓
memberName	String	✓

Example:

{
  "memberId": 0,
  "memberName": "string"
}

McpServerResponse

Field	Type	Required	Description
appUuid	String
authMetadata	Dict[str, Any]
connectionType	Literal['mcp_server']		Default: mcp_server
createdAt	DateTime	✓
creatorId	Integer
creatorName	String
credentialId	Integer
description	String
enabled	Boolean	✓
headerSecretNames	Array
iconUrl	String
id	Integer	✓
lastConnectedAt	DateTime
mcpUrl	String	✓
name	String	✓
oauthClientId	String
permissions	Integer		Default: 0
registrationUrl	String
serverInstructions	String
serverName	String
serverVersion	String
slug	String	✓
state	String	✓
supportsDirectAuth	Boolean	✓
tools	Array<McpToolResponse>
updatedAt	DateTime	✓
uuid	String	✓

Example:

{
  "connectionType": "mcp_server",
  "id": 0,
  "uuid": "string",
  "name": "string",
  "enabled": false,
  "slug": "string",
  "mcpUrl": "string",
  "state": "string",
  "supportsDirectAuth": false,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "permissions": 0
}

McpToolResponse

Field	Type	Required	Description
description	String
inputSchema	Dict[str, Any]
name	String	✓

Example:

{
  "name": "string"
}

OAuthDiscoveryRequest

Field	Type	Required	Description
oauthServerUrl	String	✓

Example:

{
  "oauthServerUrl": "string"
}

OAuthDiscoveryResponse

Field	Type	Required	Description
error	String
metadata	Object
success	Boolean	✓

Example:

{
  "success": false
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers - List
• POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/oauth-discovery - Oauth Discovery
• DELETE /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id} - Delete Server Id
• GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id} - Get Server Id
• POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/credentials - Credentials
• POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/disable - Disable
• POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/enable - Enable
• GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/icon - Icon
• GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/members - Members
• GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/oauth/authorize - Authorize
• GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/prompts - Prompts
• GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/resources - Resources
• POST /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/test - Test
• GET /api/v2/w/{workspace_uuid}/app-connections/mcp-servers/{server_id}/tools - Tools

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:

• data - See OAuthDiscoveryRequest

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)

Response: Object

---

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)

Response: 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)

Response: Response

---

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)

---