MCP Connector API
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Connector API is an Express.js-based integration service responsible for bridging the Choose Your Own Adventure (CYOA) ecosystem with various Model Context Protocol (MCP) servers. Its primary purpose is to facilitate semantic querying of user data from external platforms such as GitHub, Linear, and Notion, and to aggregate this context for use in narrative generation.
As a core component of the monorepo, the service handles authentication, connection pooling, and data normalization. It acts as a middle layer between the user-facing cyoa-engine and the backend narrative-ai service, ensuring that personalized story branches are grounded in real-world user data.
Sources: README.md:38-46, apps/mcp-connector/README.md:1-10
Service Architecture
The service is built using Node.js and Express, leveraging a custom mcp-sdk for server communications. It utilizes middleware for CORS and JSON parsing to support cross-origin requests from the frontend engine.
The diagram above illustrates the request flow from the frontend through the connector service to external data providers.
Sources: apps/mcp-connector/src/index.ts:1-15, packages/mcp-sdk/src/index.ts:18-25
API Endpoints
The MCP Connector exposes several RESTful endpoints for managing connections and retrieving semantic data.
Connection Management
These endpoints manage the state of connections to various third-party MCP servers.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/mcp/connections | Lists all supported and active MCP connections. |
POST | /api/mcp/connect | Establishes a connection to a specific MCP server. |
DELETE | /api/mcp/disconnect/:serverId | Terminates an active connection. |
Sources: apps/mcp-connector/src/index.ts:20-29, apps/mcp-connector/README.md:15-18
Semantic Querying & Context
The core functionality of the API is centered around retrieving semantically relevant data for story personalization.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/mcp/query | Executes a semantic query against a specified MCP server. |
GET | /api/mcp/context/:userId | Aggregates context from all connected MCPs for a specific user. |
Sources: apps/mcp-connector/src/index.ts:32-55, apps/mcp-connector/README.md:21-22
Data Models and Types
The service relies on standardized TypeScript interfaces defined in the shared-types package to ensure consistency across the monorepo.
MCP Connection Schema
Represents the configuration and status of an external server link.
export interface MCPConnection {
id: string;
name: string;
type: 'github' | 'linear' | 'notion' | 'filesystem' | 'custom';
status: 'connected' | 'disconnected' | 'error';
config: MCPConfig;
}
Sources: packages/shared-types/src/index.ts:6-12
Semantic Query Schema
Defines the structure of a request to retrieve context-aware data.
export interface SemanticQuery {
server: string;
query: string;
filters?: QueryFilters;
options?: QueryOptions;
}
Sources: packages/shared-types/src/index.ts:22-27
Implementation Details
Semantic Query Execution
When a query is received via the /api/mcp/query endpoint, the service uses the MCPClient from the mcp-sdk. The client implements a caching strategy to optimize performance and reduce redundant external requests.
The sequence diagram demonstrates the internal logic of the query execution, highlighting the cache-first approach.
Sources: packages/mcp-sdk/src/index.ts:71-105
Configuration
The service is configured via environment variables to manage port settings and caching policies.
| Variable | Description | Default |
|---|---|---|
PORT | The port the Express server listens on. | 3001 |
MCP_CACHE_TTL | Time-to-live for cached semantic query results (seconds). | 3600 |
NODE_ENV | Deployment environment (development/production). | development |
Sources: apps/mcp-connector/src/index.ts:9, apps/mcp-connector/README.md:26-30
Summary
The MCP Connector API serves as the critical data acquisition layer for the Prime AI Agents ecosystem. By abstracting the complexities of multiple Model Context Protocol integrations into a unified REST API, it allows the story engine to dynamically inject real-world context into interactive narratives. Its use of the mcp-sdk and shared-types ensures that data retrieval remains type-safe and efficient through built-in caching and connection management.