Adding New MCP Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Adding new Model Context Protocol (MCP) integrations allows the platform to semantically query external data sources like GitHub, Linear, or Notion to personalize narrative experiences. The integration process involves defining types in the shared library, implementing connection logic in the SDK, and exposing endpoints via the connector service.
The architecture relies on a centralized mcp-connector service that acts as a bridge between the frontend cyoa-engine and various MCP servers. This service uses the mcp-sdk to manage connections and execute semantic queries that provide real-world context to the AI narrative generator.
Sources: README.md:14-30, apps/mcp-connector/README.md:3-10
Architecture Overview
The integration follows a tiered architecture where types are shared across the monorepo, and logic is encapsulated within specific packages and applications.
The diagram above illustrates the flow from the user interface through the connector service to the external MCP servers.
Sources: README.md:20-40, apps/mcp-connector/src/index.ts:31-60
Step 1: Defining the MCP Type
Before adding an integration, the server type must be recognized by the system. This is handled in the shared-types package to ensure type safety across the monorepo.
The MCPConnection interface defines the structure for all connected servers. To add a new integration, ensure the type property in MCPConnection supports your new source.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the connection instance. |
name | string | Display name for the MCP server. |
type | github | linear | notion | filesystem | custom | The category of the MCP integration. |
status | connected | disconnected | error | Current operational state of the connection. |
config | MCPConfig | Configuration including URL, tokens, and capabilities. |
Sources: packages/shared-types/src/index.ts:7-15
Step 2: SDK Implementation
The MCPClient class in the mcp-sdk package manages the lifecycle of connections. New integrations must be compatible with the connect and executeQuery methods.
Connection Logic
The connect method takes a serverId and an MCPConfig object. For new integrations, you must ensure the configuration provides the necessary serverUrl and authToken.
// packages/mcp-sdk/src/index.ts:32-41
async connect(
serverId: string,
config: MCPConfig
): Promise<Result<MCPConnection>> {
// Logic to establish protocol-level connection
const connection: MCPConnection = {
id: serverId,
name: serverId,
type: 'custom', // Map to specific type if needed
status: 'connected',
config,
};
this.connections.set(serverId, connection);
return { success: true, value: connection };
}
Sources: packages/mcp-sdk/src/index.ts:32-55, packages/mcp-sdk/README.md:20-30
Semantic Query Builder
Integrations should leverage the SemanticQueryBuilder to allow the mcp-connector to request data using natural language or structured filters.
The sequence diagram shows how the SDK handles query execution and caching for any new integration.
Sources: packages/mcp-sdk/src/index.ts:76-115, packages/mcp-sdk/README.md:32-45
Step 3: Connector Service Integration
The mcp-connector service exposes the new integration to the rest of the application via REST endpoints.
- List Connections: Update
GET /api/mcp/connectionsto include the new service in the available integrations list. - Handle Queries: The
POST /api/mcp/queryendpoint receives aserveridentifier and routes it through theMCPClient.
Endpoint Configuration
| Endpoint | Method | Purpose |
|---|---|---|
/api/mcp/connect | POST | Initialize a connection to a new MCP server. |
/api/mcp/query | POST | Run semantic queries against the new server. |
/api/mcp/connections | GET | Retrieve the status of all configured integrations. |
Sources: apps/mcp-connector/src/index.ts:23-45, apps/mcp-connector/README.md:18-28
Step 4: Narrative AI Context Injection
Once the MCP is connected and queryable, the data is used by the narrative-ai service to personalize scenes. The mcp-connector aggregates context from multiple sources, which is then passed to the LLM.
// Example of how the system uses connected MCPs for context
// Derived from README.md usage examples
const githubContext = await mcpClient.query('github', {
semantic: 'recent repositories and contributions',
filters: { timeframe: '30days' }
});
const narrative = await narrativeAI.generate({
scene: 'office_scenario',
context: { github: githubContext },
userProfile: currentUser
});
Sources: README.md:168-185, packages/shared-types/src/index.ts:133-145
Conclusion
Adding a new MCP integration requires registration in the shared type system, implementation of connection logic within the SDK client, and exposing the functionality through the connector's API. This enables the Narrative AI to ingest real-world data, creating a personalized "OmniAgent" experience tailored to the user's specific external context.