​

One Server, Many Agents

​

How the “one client, one server” pattern sneaks into production

1. You open the official @modelcontextprotocol/sdk docs.
2. You copy the example that spins up a server.
3. You attach a transport (stdio, HTTP, SSE, or Streamable HTTP).
4. You connect an MCP client, see your tools, call them, and ship a demo.

• One IDE ↔ one MCP client ↔ one server.
• Logs are readable.
• JSON-RPC messages look clean.
• You can restart everything with a single command.

• A second IDE instance for another developer.
• A background worker using the same tools.
• A dashboard that introspects tools and runs them on behalf of users.
• Maybe even multiple agents orchestrating workflows together.

• N agents = N server processes Each agent spins its own server, often as a child process or a separate container.
• Zombie servers When a client crashes, the server it launched may keep running.
• Scattered logs and state Caches, warmups, and logs live in different processes.
• Awkward auth stories Access tokens and OAuth flows are tied to a single client/server pair.

You accidentally treated your MCP server as a client-owned subprocess instead of a shared, long-lived service.

​

Why this isn’t really about stdio vs HTTP vs SSE

• “Maybe stdio is the problem.”
• “Maybe SSE is the problem.”
• “Maybe I should just switch to Streamable HTTP and everything will be fine.”

• If your code assumes one transport = one connection = one client,
• Then it doesn’t matter whether that transport is stdio, SSE, or Streamable HTTP,
• You’ll still end up multiplying servers for every serious client.

• a homegrown session store,
• hand-managed transport IDs,
• per-app routing,
• DIY auth integration,
• and a bunch of conditionals sprinkled across tools and handlers.

​

The real problem you’re hitting

• Session IDs & transport identity So requests don’t collide across clients and nodes, and you can safely resume or route streams.
• Per-app scoping So multiple products/tenants can share one host without stepping on each other.
• Auth surfaces Remote IdP or local issuer, wired consistently and scoped correctly to apps and tools.
• Lifecycle management Sessions that can be created, resumed, and ended in a way that survives proxies, restarts, and load balancers.
• DI & hooks So you can inject config, secrets, caches, tenants, and logging without duplicating boilerplate in every tool.

• “Here are my tools and apps, written like normal TypeScript services.”
• “Give me a multi-agent, multi-app MCP server that Just Works.”

​

What we actually want from an MCP server

1. Multi-client by design
   • Many IDEs, agents, and services share one server.
   • Sessions keep each client isolated and resumable.
   • Transport identity is stable across reconnections and nodes.
2. Multi-app composition
   • Group tools into apps by product/domain/tenant.
   • Sometimes expose a unified toolbox.
   • Sometimes isolate apps with separate auth and base paths.
   • Sometimes expose an app as a standalone MCP server.
3. Auth-aware tool surface
   • The tools a client sees are based on who is logged in, not just what’s deployed.
   • OAuth scopes and identities matter.
4. Typed code with DI
   • Tools look like clean TypeScript handlers.
   • Inputs/outputs are validated with Zod.
   • Dependencies (DB, caches, external APIs) are injected via DI.
5. Adapters for existing systems
   • Already have REST APIs? Use OpenAPI, not Ctrl+C/Ctrl+V into new @Tool classes.

​

What FrontMCP flips to “on by default”

​

Standard MCP vs FrontMCP (visually)

• On the left: the “one client, one server” pattern duplicated per agent.
• On the right: one FrontMCP server hosting many apps and many agents in a spec-aligned way.

​

Show me the code (multi-agent, multi-app, scoped & authenticated)

• A server with Streamable HTTP.
• Two apps: billing and docs.
• Per-app auth for billing.

import 'reflect-metadata';
import { FrontMcp, LogLevel } from '@frontmcp/sdk';
import BillingApp from './billing.app';
import DocsApp from './docs.app';

@FrontMcp({
  info: { name: 'FrontMCP Demo', version: '1.0.0' },

  // Host multiple apps; split makes base paths & auth per-app:
  splitByApp: true,
  apps: [BillingApp, DocsApp],

  // Streamable HTTP host (multi-client capable)
  http: {
    port: 3001,
    entryPath: '', // align with your .well-known PRM resourcePath, can be /mcp to prevent conflicts
  },

  logging: { level: LogLevel.INFO },
})
export default class Server {}

import { App } from '@frontmcp/sdk';
import CreateInvoice from './tools/create-invoice.tool';

@App({
  id: 'billing',
  name: 'Billing',
  tools: [CreateInvoice],
  // Per-app auth surface:
  auth: {
    type: 'remote',
    name: 'corp-idp',
    baseUrl: 'https://auth.example.com',
  },
})
export default class BillingApp {}

import { Tool, ToolContext } from '@frontmcp/sdk';
import { z } from 'zod';

@Tool({
  name: 'create_invoice',
  description: 'Create an invoice for a customer',
  inputSchema: { customerId: z.string(), amount: z.number().positive() },
})
export default class CreateInvoice extends ToolContext {
  async execute({ customerId, amount }) {
    // DI-provided services are available from the execution context if needed
    return { status: 'ok', invoiceId: `inv_${customerId}_${Date.now()}`, amount };
  }
}

• Connect over Streamable HTTP.
• Create their own sessions.
• Call billing.create_invoice (if authorized).
• Share the same app code and server instance.

​

Composition modes: one server, many ways to slice apps

​

splitByApp: false — unified tool surface per user

• All your applications are combined under one MCP server.
• A connected client can list all tools the logged-in OAuth user is allowed to see, regardless of which app defines them.
• Auth still applies, but the visible tools and resources are filtered by the user’s identity and scopes.
• If two apps define tools with the same name, FrontMCP automatically prefixes the tool name with the app id —for example: billing.create_invoice vs ops.create_invoice.

• A single, large toolbox in the IDE.
• Agents that can orchestrate across many domains (billing + docs + ops).
• One “MCP endpoint” for the whole suite, with per-user filtering.

​

splitByApp: true — per-app isolation

• Each app gets its own base path and can define its own auth.
• You can run multiple products/tenants under one server but with clearly separated surfaces.
• Clients can connect directly to the specific app they care about, while you still deploy just one server process.

• Apps have distinct consumers and security boundaries.
• You want a “microservices-like” feel, but still prefer one deployment unit.
• You’re onboarding teams gradually and want a clear line between their responsibilities.

​

Standalone apps under /{appId}

• They live inside a grouped server (for internal or cross-app usage).
• They also need to behave as standalone MCP servers for specific clients.

• The app is served under the prefix /{appId} as if it were its own MCP server.
• From the client’s perspective, /{appId} is a standalone MCP endpoint with its own discovery and tools.
• From your perspective, it’s still the same app class and the same deployment.

• Expose a clean /{appId} endpoint for partners while keeping internal tools under a unified host.
• Gradually carve out apps from a single MCP server into more “independent” endpoints without duplicating code.

​

Plugging in existing REST APIs with OpenAPIAdapter

“This is cool, but I already have a REST API. Do I really have to rewrite everything as @Tool classes?”

​

Connect your REST API with OpenAPIAdapter

1. Provide an OpenAPI document (URL or file).
2. Specify the base URL for requests.
3. Optionally plug in middleware for auth, tenancy, or logging.
4. Get a bundle of MCP tools that call your REST endpoints.

import { App } from '@frontmcp/sdk';
import { createOpenApiAdapter } from '@frontmcp/openapi-adapter';

const openApi = await createOpenApiAdapter({
  id: 'my-rest-api',
  name: 'My REST API',
  schemaUrl: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  requestMiddleware: async (req, ctx) => {
    const token = await ctx.providers.auth.getApiToken();
    req.headers['Authorization'] = `Bearer ${token}`;
    return req;
  },
});

@App({
  id: 'rest',
  name: 'REST-backed tools',
  tools: openApi.tools,
})
export default class RestApp {}

• Making your existing API “MCP-native.”
• Letting agents and IDEs call it via tools.
• Avoiding a full parallel tool implementation.

​

Migration playbook (keep your tools; change your host)

​

FAQs

​

Where to go next