MCP gateway

The MCP gateway is the universal Model Context Protocol surface in front of Platos. One endpoint federates four tool families: entity-pushed tools, trigger.dev meta-tools, Platos skills, and the Platos control plane. Any MCP client (Claude Desktop, OpenAI's agents, your own) gets one tool catalogue keyed off the caller's identity, scope, and ACLs.

What it is

A single MCP endpoint at /mcp plus per-entity endpoints at /mcp/entities/{slug}. The gateway:

Federates: enumerates tools from all four families on each tools/list MCP call. The same federation that the agent runtime uses internally is exposed externally with consistent semantics.
Authenticates: three identity modes (PIFSP-22): anonymous (limited public tools), OIDC federation (delegated user identity), bearer PAT (long-lived programmatic access).
Authorises: PermissionGatewayService resolves the caller's effective tool list. Cross-scope cuts, per-tool ACLs, per-entity opt-ins all enforced here.
Brands: per-entity endpoints carry the entity's name, description, and logo (PIFSP-24); a customer pointing Claude Desktop at /mcp/entities/acme sees "Acme Tools" in the connector picker.

MCPRouter is the request dispatcher. MCPPlatformController exposes the project-level endpoint; MCPEntityController exposes the per-entity endpoint. MCPToolACLService enforces the per-tool opt-in (PIFSP-25).

The four tool families:

Entity tools mirrored from connected entities. The gateway reuses the registry; no double-registration.
Trigger meta-tools (spawn_bgo, list_bgos, schedule_bgo, agent_batch).
Platos skills (platos-rag, platos-code-runner, etc.).
Control plane (agents.create, threads.list, etc.). The Platos-as-a-product surface, useful for ops automation.

Why it matters

Without the gateway, an MCP client wanting to use a Platos-backed tool has to know which entity owns it, hold the entity's auth, and connect to four different surfaces. The gateway collapses that into one URL and one auth flow. The 4-tier permission model lets you expose the same tools to different audiences with different cuts: a public-facing MCP exposes the safe subset, an admin-facing MCP exposes everything.

The per-entity endpoints + branding are how an entity's tools can be consumed as if they were the entity's own MCP server. From a user's perspective, "Acme MCP" is in their MCP catalogue; the fact that it federates through Platos is an implementation detail.

How to use it

Connect an MCP client

Point your MCP client at:

https://platos.example.com/mcp

Authenticate with a PAT (Authorization: Bearer pmt_...). The client lists tools; you call them.

Per-entity endpoint

https://platos.example.com/mcp/entities/acme

Tools list scopes to the entity's pushed tools plus any Platos skills the entity has opted in.

Identity modes

Anonymous: no auth header. Only tools flagged public: true are exposed. Use cases: read-only public data, demo skills.
OIDC: Authorization: Bearer <oidc-id-token>. The gateway federates with your OIDC provider, resolves the user, and applies per-user ACLs.
Bearer PAT: Authorization: Bearer pmt_.... The PAT carries a fixed scope and an explicit ACL.

Per-tool ACL

In the entity's MCP config tab, toggle individual tools on/off for the gateway. Defaults are conservative (off for new tools); enable explicitly when you want them public.

Brand the endpoint

Per-entity endpoints expose serverInfo (name, description, logo, support URL) on the MCP handshake. Configure on the entity's detail page.

Effective tools view

GET /agent/v1/entities/:entityId/mcp/effective-tools?identity=... returns the resolved tool list for a given identity. Useful for "did Acme's user really see this tool?" debugging.

Common pitfalls

The gateway is the cross-scope cut. A bug in permission-gateway.service.ts can leak tools across orgs. Audit the test bar; the cross-scope IDOR probes cover this path.
Anonymous mode is opt-in per tool. A naively published tool with public: true is callable by any unauthenticated client. Treat public: true as a deliberate decision, not a default.
OIDC federation requires OIDC_ISSUER, OIDC_AUDIENCE, and OIDC_JWKS_URL env vars. Misconfigured OIDC silently rejects valid tokens.
The Settings -> Integrations route exists in two scopes (project and org) with similar names (drift D-006). The org-scoped page is for OAuth-style integrations like Slack; the project-scoped page is for MCP and webhook config. Cross-link from this doc to disambiguate.

MCP tokens and PATs: the bearer tokens this gateway accepts.
Tools: the registry the gateway federates.
Connected entities: the per-entity tool source.
Auth modes: the same three modes apply, with PAT as the long-lived bearer.