Multi-Tenancy Support with Keycloak

[johnidm]

I'm implementing an MCP server with OAuth authentication using Keycloak as the Identity Provider, and I need to support multi-tenancy where each tenant has its own Keycloak realm.

Context

In our architecture:

• Each tenant (organization) has its own Keycloak realm (e.g., tenant-a, tenant-b)
• OAuth discovery endpoints need to be tenant-aware
• MCP endpoints are tenant-scoped: /{tenant}/mcp - My API identifies the tenant at runtime via a proxy.

How Keycloak Multi-Tenancy Works

Keycloak implements multi-tenancy through realms, where each realm is a complete isolation unit containing:
URL Structure:

https://keycloak.example.com/auth/realms/{REALM_NAME}/...

Example endpoints per realm:

Tenant A (realm: company-a):

https://keycloak.example.com/auth/realms/company-a/.well-known/openid-configuration
https://keycloak.example.com/auth/realms/company-a/protocol/openid-connect/auth
https://keycloak.example.com/auth/realms/company-a/protocol/openid-connect/token

Tenant B (realm: company-b):

https://keycloak.example.com/auth/realms/company-b/.well-known/openid-configuration
https://keycloak.example.com/auth/realms/company-b/protocol/openid-connect/auth
https://keycloak.example.com/auth/realms/company-b/protocol/openid-connect/token

Questions for the Community

• Has anyone implemented multi-tenancy with MCP OAuth authentication?
• Are there plans to support multi-tenancy in the SDK?
• What’s the recommended architecture for this use case?
• Should we contribute a multi-tenancy extension to the SDK?

I was thinking about creating a workaround using a custom provider that dynamically switches realms and changes the authorization_servers. However, I’m not sure whether it’s possible to change the authorization_servers property at runtime.

[johnidm]

Just sharing my workaround.

I created a middleware that resolves the tenant based on the subdomain, and I create the MCPAuth instance inside that middleware.

Note that I can get the token from the tool declaration and use it to call external APIs.

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from 'zod';
import { MCPAuth, fetchServerConfig } from 'mcp-auth';

const app = express();
const port = 3001;

const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
});

const server = new McpServer({
    name: 'mpc-echo',
    version: '1.0.0'
});


const tenantResolverMiddleware = async (req, res, next) => {

    // Discover the tenant based on the subdomain
    const baseUrl = `${req.protocol}://${req.get('host')}`;
    const hostname = req.hostname;
    const hostnameParts = hostname.split('.');

    const subdomain = hostnameParts.length > 1 ? hostnameParts[0] : null;
    const tenant = subdomain || 'plataforma'

    // Fetch the authorization server configuration from Keycloak based on the realm (tenant) 
    const url = 'https://mykeycloak.com/auth/realms/' + tenant;
    const authServerConfig = await fetchServerConfig(url, {
        type: 'oidc'
    });

    // Initialize MCPAuth with the authorization server configuration
    const mcpAuth = new MCPAuth({
        protectedResources: [
            {
                metadata: {
                    resource: baseUrl,
                    authorizationServers: [authServerConfig],
                    scopesSupported: ['openid', 'profile', 'email'],
                },
            },
        ],
    });

    const router = mcpAuth.protectedResourceMetadataRouter();

    // Handle the /mcp endpoint for authentication
    if (req.path === '/mcp') {
        mcpAuth.bearerAuth('jwt', {
            resource: baseUrl,
        })(req, res, next);
    }

    return router(req, res, next);
};

app.use(tenantResolverMiddleware);

server.registerTool(
    "echo",
    {
        description: "Echo tool",
        inputSchema: {
            message: z.string().describe("The message to echo back.")
        }
    },
    async ({ message }, extra) => {
        const authorization = extra.requestInfo?.headers?.authorization;
        // Can be used to access an external API for performa
        console.log(authorization);
        
        return {
            content: [
                {
                    type: "text",
                    text: `Message: ${message}`
                }
            ]
        };
    }
);

await server.connect(transport);

app.post('/mcp', async (req, res) => {
    await transport.handleRequest(req, res);
});

app.listen(port, () => {
    console.log(`Streamable MCP Server listening at http://localhost:${port}`);
    console.log(`Streaming endpoint is http://localhost:${port}/mcp`);
});\