MCP Server Connections

Register MCP servers and create authentication bindings so AI agents can securely invoke external tools at runtime.

---

Overview

Connections are created per (server, scope) pair and drive runtime authentication when LangChain tools invoke the MCP server.

Prerequisite: OAuth-backed MCP servers depend on the connector flow documented in the OAuth Connectors guide.

API Summary

All endpoints live under /api/ai-mentor/orgs/{org}/users/{user_id}/.

Use Authorization: Token ... authentication. Only tenant admins may create/update servers and connections.

Server Registration

Create a server record

POST /api/ai-mentor/orgs/acme/users/alice/mcp-servers/ HTTP/1.1
Authorization: Token {{TOKEN}}
Content-Type: application/json

{
  "name": "Google Drive MCP",
  "description": "Search and index Drive documents",
  "url": "https://drive-mcp.example.com",
  "transport": "sse",
  "auth_type": "oauth2",
  "is_featured": false,
  "is_enabled": true
}

Response:

{
  "id": 9,
  "platform": 42,
  "name": "Google Drive MCP",
  "description": "Search and index Drive documents",
  "url": "https://drive-mcp.example.com",
  "transport": "sse",
  "auth_type": "oauth2",
  "is_featured": false,
  "is_enabled": true,
  "created_at": "2025-11-12T12:14:50Z",
  "updated_at": "2025-11-12T12:14:50Z"
}

Transport options: sse, websocket, streamable_http.

Auth types: none, token, oauth2.

If auth_type is token, populate the credentials field with the full header value (e.g., "Bearer abc123"). You can set it at creation time or later via PATCH /mcp-servers/{id}/.

Creating Connections

Connections map a server to a scope (platform, user, or mentor) and an authentication secret.

Token-based platform connection

{
  "server": 9,
  "scope": "platform",
  "auth_type": "token",
  "credentials": "Token super-secret",
  "authorization_scheme": "Token",
  "extra_headers": {
    "x-mcp-client": "mentor-ui"
  }
}

OAuth-based user connection

1. Ensure a ConnectedService exists for the same provider/service pair (see OAuth Connectors).
2. Create the connection referencing the connected_service ID:

{
  "server": 9,
  "scope": "user",
  "auth_type": "oauth2",
  "user": "alice",
  "connected_service": 77
}

Mentor-scoped connection

Mentor-scoped connections bind credentials to a specific mentor while keeping the server reusable:

{
  "server": 9,
  "scope": "mentor",
  "auth_type": "token",
  "mentor": 123,
  "credentials": "Token scoped-to-mentor",
  "authorization_scheme": "Token"
}

The mentor's platform_key must match the current tenant. If platform is omitted, the API infers it from the tenant.

Updating and deactivating connections

• PATCH /mcp-server-connections/{id}/ to toggle is_active, swap the linked connected_service, or update headers.
• DELETE /mcp-server-connections/{id}/ removes the record entirely.

Runtime Behavior

When LangChain invokes the server:

1. The runtime calls MCPServer.resolve_connection(platform, user, mentor).
2. Preference order:
   • Most recent user-scoped connection (matching user or their ConnectedService.user).
   • Mentor-scoped connection that matches the active mentor.
   • Platform-scoped connection for the tenant.
   • Featured server fallbacks (is_featured=true with global platform).
3. For OAuth connections, the linked ConnectedService is refreshed if nearing expiry (no front-end action required).
4. Headers are generated by MCPServerConnection.render_headers(), combining stored headers, tokens, and authorization schemes.

Front-end Notes

• Server first, then connection. The connection endpoints expect a valid server ID.
• OAuth prerequisite. Do not display "Connect" UI for auth_type=oauth2 servers unless the user has completed the relevant OAuth flow; otherwise the API returns 400.
• Scope hints. Use the server's auth_type to drive the form layout:
  • none: Informational text only.
  • token: Inputs for authorization_scheme, credentials, and optional header key-value pairs.
  • oauth2: A ConnectedService picker filtered by provider/service.
• Masking. The API never returns the original raw token once stored.

Troubleshooting