MCP gateway

The Fides MCP gateway lets AI agents work with Fides through the Model Context Protocol (opens in a new tab) — with every call authorized as the signed-in user. An agent connected through the gateway can do exactly what its user can do in Fides, and nothing more: calls run under the user's own role-based access control, and the gateway tells the agent which scopes an operation requires so denied requests come back actionable instead of opaque.

Fides hosts the complete OAuth 2.1 authorization flow itself — discovery, dynamic client registration, PKCE, refresh tokens, and revocation — so connecting an MCP client requires no API keys, no service tokens, and no configuration files containing credentials. Users sign in through a browser with their Fides username and password.

Enable the gateway

The gateway is disabled by default. Enable it on the Fides server:

Environment variable	Description
`FIDESPLUS__MCP_GATEWAY__ENABLED`	Set to `True` to mount the gateway at `/mcp`.
`FIDESPLUS__MCP_GATEWAY__ISSUER_URL`	The externally reachable origin MCP clients redirect to during sign-in. Defaults to the Fides server URL; set it only when the public origin differs from the internal one — for example, behind Docker or a reverse proxy.

The gateway serves MCP over streamable HTTP at https://<your-fides-host>/mcp/.

Connect an MCP client

Add Fides to any MCP client that supports streamable HTTP and OAuth. For Claude Code (opens in a new tab):

claude mcp add --transport http fides https://<your-fides-host>/mcp/

No tokens or auth flags are needed. On first connection the client discovers the Fides authorization server, registers itself, and opens a browser window to the Fides sign-in page. Sign in with your Fides username and password — including the root user — and the client completes the flow automatically. Tokens refresh silently for the life of the session.

Use HTTPS for all deployed instances. OAuth 2.1 requires it; plain HTTP is permitted only for localhost development.

Work with the Fides API

The gateway exposes the entire Fides REST API through three meta-tools, so agents discover operations on demand instead of loading hundreds of tool definitions:

Tool	Purpose
`api_search`	Find operations by keyword. Returns each match's `operation_id`, method, path, parameters, and the OAuth scopes it requires.
`api_describe`	Get one operation's full schema — path and query parameters, request body, response shape — plus its `required_scopes` and a plain-language access note.
`api_call`	Invoke an operation. The call runs as the signed-in user under Fides RBAC.

An agent works through them progressively: search for the operation, describe it to learn the inputs and required scopes, then call it.

Permission guidance on denied calls

When a call fails authorization, the gateway attaches the exact scopes the user is missing:

{
  "status_code": 403,
  "body": { "detail": "Not Authorized for this action. Required scope(s): [data_category:create]" },
  "access_denied": {
    "required_scopes": ["data_category:create"],
    "guidance": "This call runs as you, under Fides RBAC. Your token must carry the scope(s) ['data_category:create'] — directly or via an assigned role. Missing them yields a 403; ask an admin to grant a role that includes these scopes."
  }
}

The agent relays this to the user, who knows immediately which role or scope grant to request — no log diving required.

Operations the gateway never exposes

The gateway removes sensitive operations from the meta-tools entirely, so an agent can neither discover them through api_search nor invoke them through api_call — regardless of the signed-in user's permissions. This is defense in depth: RBAC already governs every call, but some data and actions should never pass through an AI agent's context or be triggered by one. An attempt to call an excluded operation returns an "Unknown operation_id" error.

The excluded operations fall into three groups.

Data-subject personal data. The gateway never exposes routes that return or accept the personal data of data subjects:

Excluded	Examples
Privacy (DSR) requests	Request results, search, attachments, comments, correspondence, access packages
Consent and preferences	Consent requests, current and historical privacy preferences, consent reporting exports
Data Rights Protocol (DRP)	Subject request exercise, status, and revocation
Manual data entry	Manual fields and manual-webhook data entered by DSR operators
External subjects	External-user creation and subject one-time-password login

Personal account records and authentication. The gateway never exposes routes that return staff account details or drive authentication:

Excluded	Examples
User records	Listing, reading, creating, updating, and deleting users; invites; system-manager assignments
Authentication	Login, logout, password reset, and email verification

Role-based access control administration remains available — roles, permissions, constraints, and role assignments are managed through separate endpoints that the gateway does expose.

Credentials. The gateway never exposes routes that read or write secret values:

Excluded	Examples
Messaging credentials	Email and SMS provider secrets, and endpoints that send a real test message
Integration credentials	Connection secret values, including system-scoped connection secrets

Read-only configuration remains available: messaging configuration and templates, and the connector-type secret schema (the field names a connector requires, never their values), stay discoverable.

Sessions and tokens

The gateway issues short-lived credentials and keeps sessions revocable:

Access tokens expire after 60 minutes. Clients rotate to a fresh token automatically using their refresh token, so live sessions are uninterrupted.
Refresh tokens rotate on every use and are stored server-side, so ending a session server-side is immediate: revoke the refresh token and the session ends within the access-token window at most.
Revocation is honored instantly. A client that revokes its access token (RFC 7009) is cut off immediately, not at expiry.

To switch Fides accounts in an MCP client, clear the client's stored authentication and reconnect — the browser sign-in runs again for the new user.

Creating Clients Overview