# MCP Server Connections

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

---

## Overview

| Term | Description |
| --- | --- |
| **MCP Server** | Metadata describing an external Model Context Protocol server (name, transport, auth type, etc.). Tenants can register multiple servers. |
| **MCP Server Connection** | An authentication binding between a tenant (or user) and an MCP server. Supports token-based and OAuth-based credentials. |
| **Scope** | Determines whether the connection is user-specific (`user`), mentor-specific (`mentor`), or tenant-wide (`platform`). |

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](/docs/developer/agents/mcp-authentication/oauth-connectors) guide.

## API Summary

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

| Capability | Endpoint | Method |
| --- | --- | --- |
| List servers | `/mcp-servers/` | `GET` |
| Create server | `/mcp-servers/` | `POST` |
| Update server | `/mcp-servers/{id}/` | `PUT` / `PATCH` |
| Delete server | `/mcp-servers/{id}/` | `DELETE` |
| List connections | `/mcp-server-connections/` | `GET` |
| Create connection | `/mcp-server-connections/` | `POST` |
| Update connection | `/mcp-server-connections/{id}/` | `PUT` / `PATCH` |
| Delete connection | `/mcp-server-connections/{id}/` | `DELETE` |

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:

```json
{
  "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

```json
{
  "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](/docs/developer/agents/mcp-authentication/oauth-connectors)).
2. Create the connection referencing the `connected_service` ID:

```json
{
  "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:

```json
{
  "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

| Issue | Resolution |
| --- | --- |
| `400 Selected MCP server is not available to the current tenant.` | Bind a non-featured server scoped to the current tenant or mark it `is_featured=true`. |
| `400 OAuth2 connections require a connected service.` | Create the OAuth connector first; ensure you pass the correct `connected_service` ID. |
| Connection falls back to platform credentials unexpectedly | Confirm the user connection's `is_active` flag. Ensure the `ConnectedService.user` matches the invoking user. |