MCP Service API

The MCP Service provides endpoints for discovering available MCP servers, managing OAuth connections, and handling MCP instances. It integrates with Composio for OAuth flows and manages the complete lifecycle of MCP server connections.

MCP System Overview

Authentication

All endpoints require a valid Bearer token in the Authorization header and appropriate RBAC permissions. Required Permissions:

mcp:read - Read MCP servers and instances
mcp:write - Connect accounts and manage instances

Base URL

/api/mcp

MCP Server Discovery

List All MCP Servers

Retrieve all available MCP servers in the platform.

curl -X GET "{{baseUrl}}/api/mcp/list_servers" \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/mcp/list_servers Response Fields:

Field	Type	Description
`servers`	array	List of MCP server objects
`servers[].id`	string	Server UUID
`servers[].name`	string	Server display name
`servers[].toolkit_name`	string	Official toolkit name
`servers[].toolkit_slug`	string	URL-safe identifier
`servers[].toolkit_logo`	string	Logo URL (nullable)
`servers[].created_at`	string	ISO 8601 timestamp
`servers[].server_instance_count`	number	Total user instances

Get Server with Tools

Retrieve detailed information about an MCP server including all available tools.

curl -X GET "{{baseUrl}}/api/mcp/server_with_tools?server_id=a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6" \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/mcp/server_with_tools Query Parameters:

Parameter	Required	Type	Description
`server_id`	Yes	string	MCP server UUID

Connection Management

Connect Account (Start OAuth)

Initiate OAuth flow to connect an MCP server to the user’s account.

curl -X POST "{{baseUrl}}/api/mcp/connect_account" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "flow_type": "chat"
  }'

Endpoint: POST /api/mcp/connect_account Request Body:

Field	Type	Required	Description
`server_id`	string	Yes	MCP server UUID to connect
`flow_type`	string	No	Flow context (e.g., “chat”, “settings”)

Response Fields:

Field	Type	Description
`id`	string	Connected account ID from Composio
`status`	string	Connection status (usually “pending”)
`redirect_url`	string	OAuth URL to redirect user to
`connectionData`	object	Additional connection metadata

Flow:

Call this endpoint with server_id
Redirect user to redirect_url
User completes OAuth on external service
External service redirects back to callback
System automatically creates MCP instance
User redirected to frontend with success

OAuth Callback Handler

Internal endpoint that handles OAuth callbacks from external services. Endpoint: GET /api/mcp/callback Query Parameters:

Parameter	Required	Type	Description
`mcp_server_id`	Yes	string	Server UUID
`mcp_session_id`	Yes	string	Session instance ID
`flow_type`	No	string	Original flow context

Behavior:

Validates OAuth callback
Updates session status to “active”
Auto-creates MCP instance via Composio
Redirects to frontend with parameters

Frontend Redirect Format:

{frontend_url}/mcp/callback?mcp_server_id={server_id}&mcp_session_id={session_id}&flow_type={flow}

Note: This endpoint is called by OAuth providers, not by clients directly

The callback endpoint is configured in the OAuth application settings and is automatically invoked by the external service after user authorization. Clients should not call this endpoint directly.

Generate MCP URL

Generate the MCP connection URL for an active session.

curl -X POST "{{baseUrl}}/api/mcp/generate_url" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "session_id": "session-uuid"
  }'

Endpoint: POST /api/mcp/generate_url Request Body:

Field	Type	Required	Description
`server_id`	string	Yes	MCP server UUID
`session_id`	string	Yes	MCP session UUID (from connect_account)

Response:

Field	Type	Description
`mcp_url`	string	Full MCP connection URL
`status`	string	Generation status

Usage: The generated URL is used internally by the MCP Playground to establish connections with MCP servers.

Instance Management

List User Instances

Retrieve all MCP instances (connections) for the authenticated user’s organization.

curl -X GET "{{baseUrl}}/api/mcp/list_instances?org_id=your-org-id&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/mcp/list_instances Query Parameters:

Parameter	Required	Type	Description
`org_id`	Yes	string	Organization UUID
`status`	No	string	Filter by status: active, pending, inactive

Response: Array of MCP instance objects with fields:

Field	Type	Description
`id`	string	Instance UUID
`status`	string	Current status
`mcp_server_id`	string	Parent server UUID
`name`	string	Custom name (nullable)
`created_at`	string	ISO 8601 timestamp

Update Instance

Update the custom name of an MCP instance.

curl -X PUT "{{baseUrl}}/api/mcp/instance?mcp_instance_id=inst-uuid" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Primary Gmail Account"
  }'

Endpoint: PUT /api/mcp/instance Query Parameters:

Parameter	Required	Type	Description
`mcp_instance_id`	Yes	string	Instance UUID to update

Request Body:

Field	Type	Required	Description
`name`	string	Yes	New custom name for the instance

Delete Instance

Delete an MCP instance and disconnect from the external service.

curl -X DELETE "{{baseUrl}}/api/mcp/instance?mcp_instance_id=inst-uuid" \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: DELETE /api/mcp/instance Query Parameters:

Parameter	Required	Type	Description
`mcp_instance_id`	Yes	string	Instance UUID to delete

Behavior:

Deletes MCP instance from Composio (if active)
Removes session record from database
Revokes OAuth access tokens
Cannot be undone

Error Responses

Status Code	Description	Example
400	Bad Request	Invalid server_id or missing parameters
401	Unauthorized	Invalid or missing token
403	Forbidden	Insufficient permissions (requires mcp:write/read)
404	Not Found	MCP server or instance not found
500	Internal Server Error	Composio API failure or database error

Error Response Format:

{
  "detail": "Error message describing what went wrong"
}

Common Error Messages:

// No auth config found
{
  "detail": "No auth config found for server: server-uuid"
}

// Connection attempt not found
{
  "detail": "No connection attempt found. Please connect your account first."
}

// Instance not found
{
  "detail": "MCP instance not found"
}

// OAuth failure
{
  "detail": "Failed to create connected account: [Composio error details]"
}

Implementation Notes

OAuth Flow

Complete OAuth flow implementation:

// 1. List available servers
const servers = await listMCPServers();

// 2. User selects server (e.g., Gmail)
const gmailServer = servers.find(s => s.toolkit_slug === 'gmail');

// 3. Initiate connection
const connection = await connectMCPAccount(gmailServer.id, 'chat');

// 4. Redirect to OAuth
window.location.href = connection.redirect_url;

// 5. User completes OAuth on external site
// ... user authorizes ...

// 6. OAuth provider redirects to callback
// Backend handles: GET /api/mcp/callback?mcp_server_id=...&mcp_session_id=...

// 7. Backend redirects to frontend
// Frontend receives: /mcp/callback?mcp_server_id=...&mcp_session_id=...

// 8. Frontend can now generate MCP URL
const mcpUrl = await generateMCPUrl(gmailServer.id, sessionId);

// 9. Use MCP URL in Playground
// Pass to MCP Playground Service for tool usage

Session Management

Best practices for managing MCP sessions:

# Check user's existing connections
instances = list_instances(org_id, status="active")

# Filter by server
gmail_instances = [i for i in instances if i["mcp_server_id"] == gmail_server_id]

if gmail_instances:
    # User already connected
    instance_id = gmail_instances[0]["id"]
else:
    # Need to connect
    connection = connect_account(gmail_server_id)
    # Redirect user to OAuth...

Feature Flags

MCP functionality is controlled by feature flags:

mcp_sessions: Quota for number of MCP connections
Checked on POST /connect_account
Returns 402 Payment Required if quota exceeded

Composio Integration

The service integrates with Composio for:

OAuth Management:
- Creating connected accounts
- Generating redirect URLs
- Handling callbacks
Instance Management:
- Creating MCP instances
- Generating MCP URLs
- Deleting instances
Authentication:
- Token management
- Automatic token refresh
- Secure credential storage

Rate Limiting

Rate limits may apply based on:

Feature flag quotas (mcp_sessions)
Composio API limits
External service OAuth limits

Security Considerations

OAuth Security

OAuth tokens never exposed to client
Tokens stored securely in Composio
Automatic token refresh
Callback URL validation

Access Control

All endpoints require authentication
RBAC permissions enforced
Org-scoped operations
User isolation

Data Privacy

No MCP data stored permanently
OAuth scopes request minimal permissions
Users can revoke access anytime
Audit trail for connections

Next Steps

Explore MCP integration further:

MCP Playground Service - Chat with MCP tools
MCP Concepts - Understanding MCP architecture
Authentication Guide - Security and RBAC
Getting Started - Quick start guide

Ready to build with MCP? Check out the MCP Playground API to start using connected tools!

🎯 Welcome

🚀 Getting Started

💡 Core Concepts

🏗️ Platform Architecture

🔐 Security & Auth

📡 API Reference

🛠️ Development Guides

🚨 Troubleshooting

MCP System Overview

Authentication

Base URL

MCP Server Discovery

List All MCP Servers

Get Server with Tools

Connection Management

Connect Account (Start OAuth)

OAuth Callback Handler

Generate MCP URL

Instance Management

List User Instances

Update Instance

Delete Instance

Error Responses

Implementation Notes

OAuth Flow

Session Management

Feature Flags

Composio Integration

Rate Limiting

Security Considerations

OAuth Security

Access Control

Data Privacy

Next Steps

🎯 Welcome

🚀 Getting Started

💡 Core Concepts

🏗️ Platform Architecture

🔐 Security & Auth

📡 API Reference

🛠️ Development Guides

🚨 Troubleshooting

​MCP System Overview

​Authentication

​Base URL

​MCP Server Discovery

​List All MCP Servers

​Get Server with Tools

​Connection Management

​Connect Account (Start OAuth)

​OAuth Callback Handler

​Generate MCP URL

​Instance Management

​List User Instances

​Update Instance

​Delete Instance

​Error Responses

​Implementation Notes

​OAuth Flow

​Session Management

​Feature Flags

​Composio Integration

​Rate Limiting

​Security Considerations

​OAuth Security

​Access Control

​Data Privacy

​Next Steps

MCP System Overview

Authentication

Base URL

MCP Server Discovery

List All MCP Servers

Get Server with Tools

Connection Management

Connect Account (Start OAuth)

OAuth Callback Handler

Generate MCP URL

Instance Management

List User Instances

Update Instance

Delete Instance

Error Responses

Implementation Notes

OAuth Flow

Session Management

Feature Flags

Composio Integration

Rate Limiting

Security Considerations

OAuth Security

Access Control

Data Privacy

Next Steps