MCP Gateway

The MCP Gateway is a platform service that brokers tool calls between the Inference-Server and upstream Model Context Protocol providers. The inference server never talks to NetSuite (or any other upstream system) directly — it goes through this gateway.

What it is

A standalone capability server (Capability-Servers/MCP-Gateway) that:

• Holds the registry of provider connections for each tenant — e.g. "this NetSuite account is connected, here are its tools, this is the OAuth token to use."
• Brokers tool calls from the inference server to the appropriate upstream MCP server, injecting the right credentials.
• Manages OAuth to the upstream provider (the NetSuite-side OAuth, not the platform sign-in OAuth).
• Sends heartbeats back to the inference server during tool execution, which is why MCP-routed tools survive client disconnects (see Tools — Heartbeats).

Architecture

┌─────────────────┐    HTTPS     ┌──────────────┐   MCP    ┌──────────┐
│ Inference-Server│──────────────▶│ MCP Gateway │──────────▶│ NetSuite │
└─────────────────┘   list tools  └──────────────┘  (SSE)   └──────────┘
        │                                ▲
        │   SQS request                  │ SQS reply +
        │   (tool call)                  │ heartbeats
        └────────────────────────────────┘

Two communication channels:

• HTTP for synchronous reads (list providers, fetch tool catalog, OAuth refresh, admin operations).
• SQS request/response for tool execution — async, with the gateway's worker process sending heartbeats back during long-running calls.

Providers and connections

A provider in the gateway is a connection between a tenant account and an upstream MCP server. It's also referred to as a "connection" — they're the same thing in the data model (ProviderEntry).

Each provider record carries:

Records live in DynamoDB. OAuth tokens for the upstream provider live in a separate DynamoDB table keyed by (accountDiscriminator, userPrincipal, integrationDiscriminator).

HTTP API surface

All routes require a JWT (Bearer header or Authorization cookie). Service callers must use a service-identity JWT minted via mintOnBehalfOf with the gateway as the to claim.

Upstream OAuth

The gateway does not implement upstream OAuth itself — it delegates to the platform's central OAuth service (OAUTH_DOMAIN, the same one that issues the platform JWTs developers carry). The flow:

Tool-call brokering

When the model emits a tool call for an MCP-provided tool, here's what happens:

Pluggability

The gateway's provider registry is pluggable in code via MCPPlatformDefinition:

export type MCPPlatformDefinition = {
  platformId: string;
  buildUrl: (provider, accountDiscriminator) => URL;
  getCredentials: (params) => Promise<{ accessToken: string } | null>;
  connect: (ctx) => Promise<MCPClientWrapper>;
  mapTools: (toolPrefix, rawTools) => Tool[];
};

The NetSuite provider lives at Capability-Servers/MCP-Gateway/src/platform/netsuite/ and ships these four functions. The BaseMCPPlatforms enum lists the providers loaded at boot — today that's just NetSuite.

Adding a new provider is a code change: implement the four functions, register the platform, redeploy. There is no runtime API for end-users or tenants to register an arbitrary MCP server. This is the correction to a common misreading of the platform: "MCP gateway" doesn't mean "any MCP server" — it means "our broker, with whatever providers the platform team has wired up."

Control Panel

The day-to-day UI for managing provider connections is the MCP Gateway Control Panel (Tools/rfs-ai-mcp-gateway-control-panel), a Next.js app that talks to the gateway's HTTP API.

It's the admin surface that customers and platform admins use to:

• See all providers their tenant owns, filtered or showing deleted.
• Register a new provider (form-based; runs POST /v1/mcp/providers).
• Drill into a provider to see its cached tools, assigned users, and admins.
• Trigger an OAuth refresh when the upstream token expires.
• Manually reload tools after an upstream catalog change.
• Soft-delete a provider.

Pages

Operating outside the UI

Everything the Control Panel does is also reachable via the HTTP API documented above — useful for scripted provisioning, CI integration tests, or one-off ops. For example, to register and bind a NetSuite provider end-to-end without the UI:

# 1. Create the provider
curl -X POST "$GATEWAY_URL/v1/mcp/providers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationDiscriminator": "netsuite:acme-1234",
    "accountDiscriminator": "acme",
    "label": "Acme NetSuite (prod)",
    "users": ["user@acme.com"],
    "admins": ["admin@acme.com"],
    "extensions": { "netsuite": { "suiteapp": "..." } }
  }'
 
# 2. Send the user through OAuth (returns a redirect URL)
curl -i "$GATEWAY_URL/v1/mcp/providers/$CONNECTION_ID/oauth/refresh" \
  -H "Authorization: Bearer $TOKEN"
 
# 3. After the user completes the upstream consent, reload tools
curl -X POST "$GATEWAY_URL/v1/mcp/providers/$CONNECTION_ID/reload" \
  -H "Authorization: Bearer $TOKEN"