MCP Gateway
The MCP Gateway is where you govern Model Context Protocol (MCP) traffic in a project. It does two jobs:
- Watch the MCP servers your agents use. Every MCP server that runs in the project is recorded with the tools it advertises, and you're told when that changes.
- Let agents you didn't build use those servers, under your rules. An external MCP client (Claude Code, Cursor, a vendor's agent, your own LangGraph app) connects to one gateway endpoint as a registered agent identity. It sees and can call only the tools you've entitled it to. Every call goes through the same policy checks and decision records as your own agents' calls.
Open it from Platform → MCP Gateway. It's aimed at platform owners and security or compliance staff who need to know what MCP servers can do and who can reach them.
MCP servers registered as functions get their integration credentials inside FYAI's sandbox when they start. An external agent calling through the gateway uses those servers without ever receiving the API keys or OAuth tokens behind them, and you can revoke its access without rotating anything.
The gateway exposes MCP server functions in your project to outside agents. To let Claude Code or another client manage and run your FYAI agents, workflows and other resources, use the FYAI MCP server instead.
How it fits together
External agent FYAI
(Claude Code, Cursor, …) ─────────────────────────────────────
│ POST /gateway/mcp 1. authenticate credential (every call)
│ Bearer fygw_… 2. rate limit per identity
└─────────────────────────► 3. entitled to this server and tool?
4. contained? policy decision recorded
5. start the MCP server function in the
sandbox with its integration secrets
6. call the tool, return the result
An MCP server can be reached through the gateway only if it is:
- a function of type MCP server (stdio) in the project (see Functions), and
- recorded under Servers & Surfaces, which happens the first time it runs on the platform (for example, when one of your agents uses it in a chat).
The five tabs
| Tab | What it's for | Who can act |
|---|---|---|
| Servers & Surfaces | Every MCP server that has run in the project, the tools it advertises, and changes to them. | Project Editor to acknowledge changes |
| Identities | External agents registered with the gateway, their credentials and their entitlements. | Project Editor |
| Entitlements | Same view as Identities: entitlements are managed inside each identity. | Project Editor |
| Containment | Quarantine or kill an identity, a server, or your organisation's whole gateway access. | Project Admin |
| Directories | Import agent identities from Microsoft Entra Agent ID or Okta. Preview. | Project Admin |
Anyone with access to the project can view every tab. Organisation Owners and Admins can do everything. See Members and roles.
Servers & Surfaces
A server's surface is the list of tools it advertises, with their descriptions and input schemas. FYAI records it whenever the server runs and compares it with the last one. A server can change what it does without anyone editing the function, for example when an npx package updates. A new tool, a widened parameter or a rewritten description is how a server quietly gains abilities.
| Column | Meaning |
|---|---|
| Server | Function name, and the server's own reported name. |
| Owner | Who owns the function. |
| Placement | workspace (runs beside a chat session's files) or stateless (no session files). External callers have no session, so stateless suits servers you expose through the gateway. |
| Version | Version the server reports. |
| Tools | Number of advertised tools. |
| Review | Reviewed, Changed — not reviewed or Held — tools denied. |
| Last changed | When the surface last changed. |
Expand a row to see Advertised tools (name, description and input schema) and the Change history. Each change is marked Material change or Cosmetic, lists tools added, removed and changed (with before and after), and shows whether it's been acknowledged and by whom.
Changed — not reviewed is informational: the tools still run. Held — tools denied applies only to servers whose function is set to require surface review. Their tools are refused (reason denied_surface_unreviewed) until someone selects Acknowledge this surface. The reviewer recorded is always whoever is signed in. Requiring review is a function setting that some marketplace templates turn on; it isn't editable on the Functions page.
Turn on Only servers whose surface changed to see just the servers waiting for review.
Identities, credentials and entitlements
An agent identity represents one external agent. It has:
| Part | Detail |
|---|---|
| Agent | Name and description (What it is). |
| Acts for | The person it works for (Who it acts for). Left blank, it's recorded as Acts autonomously. A client can also name the person per call with the X-FYAI-On-Behalf-Of header. |
| Source | Local (registered here) or the directory it was imported from. |
| State | Active, Disabled, Quarantined or Killed. Only active identities can authenticate. |
| Credentials | Secrets the agent uses to authenticate. |
| Entitlements | The servers and tools it may reach (Reaches). |
A new identity reaches nothing. Access is granted per server, either for every tool this server advertises (which also covers tools the server adds later) or for a single tool. If a server stops advertising a tool you granted, the grant is shown in red as stale.
Credentials look like fygw_<id>.<secret>. The secret is shown once, when issued or rotated, and only a hash is stored. Credentials issued in the app don't expire. A credential is flagged Expiring soon 14 days before an expiry set through the API. Rotate issues a replacement and revokes the old one at once, with no overlap. Revoke takes effect on the next call. Revoked credentials stay listed for the audit trail.
The gateway checks the credential, identity state and entitlement on every request, not once per session.
For step-by-step instructions, see Connect an external agent through the MCP Gateway.
Containment
Containment stops something quickly during an incident, without a deploy.
| Scope | What it stops |
|---|---|
| An agent identity | That external agent. Its credentials stop authenticating. |
| An MCP server | Calls to that server's tools, by external agents and your own platform agents. |
| This tenant's whole gateway access | Every MCP server tool call in your organisation, and your organisation's model calls as well. |
| State | Effect |
|---|---|
| Quarantine | New calls are denied. Records, history and decisions are kept for investigation. |
| Kill | The same, and a killed identity can't be issued new credentials until it's released. |
Server and tenant containment applies across all projects in your organisation, not just the one you're in. A Reason is required to contain and to release, and both are audited. Containing is also reported to Governance alerts.
In the current release, every containment, including Quarantine, also shuts down MCP servers that are already running, which fails calls in progress. Containing a server stops that server. Containing an identity or the whole tenant stops all running MCP servers in your organisation, including ones your own agents are using; they restart on their next call.
Release lifts a containment. Turn on Include released to see past containments. Decisions opens the policy decision explorer filtered to the refusals the containment caused (denied_killswitched or denied_identity_contained). See Governance.
Containing an identity always works: the gateway rejects its credentials on the next call. Refusals of server and tenant containment, and of held surfaces, come from the platform's MCP policy check, which can run in a record-only (shadow) mode where a refusal is logged as a decision but the call still goes ahead. Use Decisions to see what the policy check did with each call, rather than assuming it stopped.
Directories (preview)
Directories is meant to import agent identities from Microsoft Entra Agent ID or Okta Universal Directory instead of registering them by hand. Imported identities would arrive with no entitlements, and an identity you contained would stay contained whatever the directory says.
You can add a directory, but Sync now doesn't import anything yet and fails with an error. Register external agents by hand under Identities for now.
Limits and behaviour
| Item | Value |
|---|---|
| Endpoint | https://agent.fyai.co.nz/gateway/mcp, streamable HTTP, JSON-RPC 2.0, protocol version 2025-11-25 |
| Methods | initialize, ping, tools/list, tools/call; notifications/* accepted |
| Tool names | <server id>.<tool>, for example 1154.search_tickets |
| Rate limit | Per identity: bursts of up to 60 calls, refilling at about one call per second. Excess calls get HTTP 429 with Retry-After. |
| Cold start | If a server takes longer than 25 seconds to start, the call returns HTTP 503 with Retry-After: 15 while the server keeps starting. Retry. |
| Results | Text only. |
| Not supported | MCP resources and prompts, MCP-over-HTTP functions, servers that need a session's files |
Related
- Connect an external agent through the MCP Gateway
- Functions: registering MCP servers
- Integrations: the credentials MCP servers use
- FYAI MCP server: driving FYAI itself from an MCP client
- Governance: policy decisions and alerts