Connection & Auth Management
Relevant source files
The following files were used as context for generating this wiki page:
The Connection & Auth Management system in the MCP Games Monorepo is responsible for establishing, maintaining, and securing communications between the gaming applications and various Model Context Protocol (MCP) servers. It serves as the bridge that allows the cyoa-engine to semantically query external data sources like GitHub, Linear, and Notion to personalize narrative experiences.
This system is primarily implemented through the mcp-connector service and the mcp-sdk package. It manages the lifecycle of MCP connections, including authentication via tokens, connection pooling, and health monitoring of remote servers.
Sources: README.md:38-44, apps/mcp-connector/README.md:3-10
Architecture & Components
The connection management architecture is split between a centralized service (mcp-connector) and a client library (mcp-sdk) used by internal services.
MCP Client (SDK)
The MCPClient class is the core engine for managing local connection states and executing queries. It maintains a registry of active connections and handles the logic for connecting/disconnecting from specific servers using provided configurations.
The diagram above shows the relationship between the client manager and the connection entities.
Sources: packages/mcp-sdk/src/index.ts:18-35, packages/shared-types/src/index.ts:7-20
Connection Lifecycle
Connections transition through several states: connected, disconnected, and error. The system supports both standard integrations (GitHub, Linear, Notion, Filesystem) and custom MCP server implementations.
| Component | Description | Source |
|---|---|---|
| Connection ID | Unique identifier for the specific server instance. | shared-types/src/index.ts:8 |
| Server URL | The endpoint address of the MCP server. | shared-types/src/index.ts:18 |
| Auth Token | Secret credential used for bearer authentication. | shared-types/src/index.ts:19 |
| Capabilities | Array of features supported by the connected server. | shared-types/src/index.ts:20 |
Authentication Workflow
Authentication is managed via an authToken provided within the MCPConfig. The mcp-connector service acts as the proxy, ensuring that requests to external MCP servers include the necessary credentials retrieved from the user's connection profile.
This flow illustrates how authentication configuration is passed from the frontend through the connector to the final external server.
Sources: apps/mcp-connector/src/index.ts:31-45, packages/mcp-sdk/src/index.ts:37-58, apps/mcp-connector/README.md:18-24
API Endpoints
The mcp-connector exposes several REST endpoints for managing connections and performing authenticated actions.
Connection Management
GET /api/mcp/connections: Retrieves a list of current MCP servers and their statuses.POST /api/mcp/connect: Initiates a new connection to an MCP server using a provided configuration (URL and Token).DELETE /api/mcp/disconnect/:serverId: Terminates an active connection and removes it from the registry.
Sources: apps/mcp-connector/src/index.ts:20-28, apps/mcp-connector/README.md:19-21
Context & Querying
POST /api/mcp/query: Executes a semantic query against a specific connected server.GET /api/mcp/context/:userId: Aggregates data across all authenticated connections for a specific user to build a narrative context.
Sources: apps/mcp-connector/src/index.ts:31-54, apps/mcp-connector/README.md:24-25
Configuration Management
The system utilizes environment variables and internal interfaces to manage connection settings.
| Variable/Field | Type | Description |
|---|---|---|
MCP_CACHE_TTL | Number | Time-to-live for cached connection data and query results. |
retryAttempts | Number | Number of times the SDK will attempt to reconnect on failure (default: 3). |
defaultTimeout | Number | Milliseconds before a connection attempt is aborted (default: 5000). |
cacheEnabled | Boolean | Global toggle for query result caching. |
Sources: apps/mcp-connector/README.md:31, packages/mcp-sdk/src/index.ts:25-29
Implementation Example: Connecting
The following logic demonstrates how a connection is established using the MCPClient and the shared MCPConfig structure.
// From packages/mcp-sdk/src/index.ts
async connect(
serverId: string,
config: MCPConfig
): Promise<Result<MCPConnection>> {
try {
const connection: MCPConnection = {
id: serverId,
name: serverId,
type: 'custom',
status: 'connected',
config,
};
this.connections.set(serverId, connection);
return { success: true, value: connection };
} catch (error) {
return { success: false, error: new Error('Unknown error') };
}
}
Sources: packages/mcp-sdk/src/index.ts:37-58
Summary
Connection & Auth Management provides the foundational infrastructure for the "OmniAgent" ecosystem. By abstracting the complexities of MCP server handshakes, token-based authentication, and connection state tracking into the mcp-sdk and mcp-connector, the system allows the narrative engines to focus on data retrieval without managing individual socket or HTTP lifecycle events.