🚀 Feature Request: Support MCP servers with dynamic API keys

[hejtmii]

🎤 Tell us your idea

We have a central MCP server serving multiple users

The server passes given API key (authentication token) to the underlying Management API which uses the API key to evaluate permissions

We are using a single instance of self-hosted runtime of CopilotKit with createMCPClient configured

MCP server is defined at the FE (via setMcpServers), passing the server URL + API key of the given user

Every user has their own authentication tokens that are automatically provided and refreshed by the UI code
Tokens are short living (max 10 minutes)
One user may have more tokens (each browser window has its own)

The problem is that CopilotKit assumes that the configuration of MCP server is static during the run of the app, having a static API key

The underlying action cache is only indexed by endpointUrl, API key not included at all

CopilotKit/CopilotKit/packages/runtime/src/lib/runtime/copilot-runtime.ts

Line 1451 in 20b5d99

let actionsForEndpoint: Action<any>[] | undefined = this.mcpActionCache.get(endpointUrl);

We bypass that by appending unique query parameter to the endpointUrl ... ?uid={hash_of_api_key} so that they are cached for every API key separately. It somewhat works, BUT...

• It causes a memory leak, keeping all no longer MCP clients in the memory - There is no way to clear the cache / it has no timeout for the entries
• Every newly setup endpointUrl must initialize its available tools (which further extends the memory leak footprint), even though the server is the same

There should be some way to handle this situation, being able to have a single endpointUrl of a shared server instance, passing the API key from the individual request to the tool call.

It might be enough if the MCP tool call got the respective context (related MCP server config) in its second parameter. The custom MCP client could then extract it and add the API key dynamically to the request headers for that specific call.

Please add such feature, or advise how it could be done with the current code.

[linear]

CPK-4490 🚀 Feature Request: Support MCP servers with dynamic API keys

[copilotkit-support-bot]

CopilotKit currently assumes a static MCP server configuration, which makes dynamic API key management challenging. However, there are ways to work around this and suggestions for more robust solutions.

Details

Current MCP Implementation Limitations

• The MCPServerConfig interface only supports static API keys: { endpoint: string; apiKey?: string }
• API keys are configured once during CopilotRuntime initialization
• Actions are cached by endpoint URL only, not by user/session context
• There are no built-in cache invalidation methods for expired API keys

Existing Dynamic Capabilities

• The getServerSideActions() method can merge base endpoints with request-specific endpoints per request
• The frontend useCopilotChat hook supports dynamic MCP server updates via setMcpServers
• Request-specific endpoints passed via graphqlContext.properties.mcpServers override the base configuration
• The MCPClient interface allows for custom implementations that could handle dynamic authentication
• Request context infrastructure exists to carry user-specific data

Recommended Implementation Approaches

Approach 1: Dynamic MCP Server Configuration (Frontend-driven)

// In your React component
const { setMcpServers } = useCopilotChat();

// Update MCP servers with user-specific API keys
const updateUserMCPServers = (userId: string, apiKey: string) => {
  setMcpServers([
    {
      endpoint: "your-mcp-endpoint",
      apiKey: apiKey // Dynamic API key per user
    }
  ]);
};

// Call when user authenticates or API key changes
useEffect(() => {
  updateUserMCPServers(currentUser.id, currentUser.mcpApiKey);
}, [currentUser]);

Approach 2: Request Context Enhancement (Backend-driven)

// Extend the runtime with user context
class CustomCopilotRuntime extends CopilotRuntime {
  async getServerSideActions(graphqlContext: any) {
    // Extract user context from headers/auth
    const userId = graphqlContext.req.headers['x-user-id'];
    const userApiKey = await getUserMCPApiKey(userId);
    
    // Create user-specific MCP servers
    const userMcpServers = [{
      endpoint: "your-mcp-endpoint",
      apiKey: userApiKey
    }];
    
    // Override request MCP servers
    graphqlContext.properties = {
      ...graphqlContext.properties,
      mcpServers: userMcpServers
    };
    
    return super.getServerSideActions(graphqlContext);
  }
}

Approach 3: Custom MCP Client with Dynamic Auth

// Create a custom MCP client that handles dynamic auth
class DynamicAuthMCPClient implements MCPClient {
  constructor(private getUserApiKey: (userId: string) => Promise<string>) {}
  
  async listTools(endpoint: string, context?: any): Promise<any[]> {
    const userId = context?.userId;
    const apiKey = await this.getUserApiKey(userId);
    
    // Make request with dynamic API key
    return this.makeRequest(endpoint, { apiKey });
  }
  
  async callTool(endpoint: string, toolName: string, args: any, context?: any): Promise<any> {
    const userId = context?.userId;
    const apiKey = await this.getUserApiKey(userId);
    
    // Make tool call with dynamic API key  
    return this.makeRequest(endpoint, { apiKey, toolName, args });
  }
}

Cache Management Solutions

User-Specific Cache Keys

// Modify cache keys to include user context
const getCacheKey = (endpoint: string, userId: string) => `${endpoint}:${userId}`;

// Clear user-specific cache when API key expires
const clearUserMCPCache = (userId: string) => {
  for (const [key] of mcpActionCache.entries()) {
    if (key.endsWith(`:${userId}`)) {
      mcpActionCache.delete(key);
    }
  }
};

Time-Based Cache Invalidation

// Add TTL to cached actions
interface CachedMCPAction {
  actions: any[];
  timestamp: number;
  ttl: number;
}

const isCacheValid = (cached: CachedMCPAction) => {
  return Date.now() - cached.timestamp < cached.ttl;
};

Implementation Priority

• Immediate Solution: Use frontend setMcpServers with user-specific API keys and update MCP configuration when user auth state changes.
• Long-term Solution: Extend runtime with custom user context handling, implement user-specific caching with proper invalidation, and create a custom MCP client for advanced dynamic auth scenarios.

Documentation References:

• CopilotRuntime Configuration
• useCopilotChat Hook

Source Code References:

• Runtime Implementation
• MCP Utilities

The frontend-driven approach provides the quickest path to dynamic API key support, while backend and custom client approaches offer more robust, scalable solutions.

---

Was this helpful?

If this solution worked for you, please click on the appropriate option below to help us improve:

✅ Issue Solved | ❌ Need more help

[copilotkit-support-bot]

👋 Thanks for your feedback!

I've escalated this issue to our development team. Someone from our team will review your request and provide additional assistance shortly.

If this is blocking production, please book a meeting with us at https://cal.com/nathan-tarbert-copilotkit/15min