Connect AI agents through flespi realm MCP

Connect an OAuth-capable MCP client to a flespi realm so users can authorize AI agents without creating or sharing flespi tokens. The agent receives the permissions of the authenticated realm user and remains isolated to that realm.

• Realm MCP endpoints
• Prerequisites
• Connect an MCP client
• Permissions
• Authentication
• OAuth discovery and redirects
• Troubleshooting
• Limitations

Realm MCP endpoints

Realm MCP provides realm-wrapped mirrors of the existing flespi MCP endpoints:

The wrapped endpoints expose the same tools and behavior as their corresponding platform endpoints. See flespi AI integration for server selection, tools, costs, and general MCP behavior.

Prerequisites

Before connecting a client:

1. Create a realm and configure its users or identity providers.
2. Configure the realm role or user token ACL with POST ai/mcp and only the downstream API access the agent needs.
3. Enable the realm OAuth server.
4. Add the MCP client's exact Client ID Metadata Document (CIMD) URL to oauth_server.allowed_clients.
5. Confirm that the client supports HTTP MCP transport and OAuth discovery with a URL-based CIMD client ID.

OAuth setup is controlled by the realm owner. Each realm user authorizes the client with that user's own realm permissions.

Connect an MCP client

Replace <realm-public-id> with the public ID shown in the realm configuration, choose develop or support, and enter the corresponding realm MCP endpoint as the client's MCP server URL:

https://flespi.io/realm/<realm-public-id>/ai/mcp/develop
https://flespi.io/realm/<realm-public-id>/ai/mcp/support

For an OAuth-capable MCP client, this endpoint is normally the only server value required. On the first connection, the client receives a Bearer challenge, discovers the realm OAuth server, and starts user authorization. Do not configure a client secret or add a static Authorization header.

The realm Info tab provides integration actions for listed clients. Use the generic endpoint above when configuring another compatible MCP client manually.

Permissions

Realm MCP does not grant permissions of its own. The realm user's token ACL remains the authorization boundary. Allow POST ai/mcp and only the downstream API access required by the agent. See flespi AI integration and flespi token - access key to the flespi platform for permission configuration.

Authentication

OAuth access uses the opaque Bearer issued by the realm OAuth server.

The OAuth default scope does not provide separate MCP permissions. Access to develop, support, and downstream API operations is determined by the realm user's token ACL. OAuth grants are not bound to one MCP server as an audience, so an eligible token can use either server when its ACL permits ai/mcp.

OAuth discovery and redirects

A compatible client must meet the realm OAuth client requirements and support OAuth Protected Resource Metadata discovery from a Bearer challenge.

After authentication, the realm endpoint redirects with HTTP 307 to the corresponding /ai/mcp/develop or /ai/mcp/support mirror. The client must follow this redirect while preserving the POST method, request body, and authorization on the same origin.

Protected-resource metadata is available at:

https://flespi.io/.well-known/oauth-protected-resource/realm/<realm-public-id>/ai/mcp/develop
https://flespi.io/.well-known/oauth-protected-resource/realm/<realm-public-id>/ai/mcp/support

Clients normally discover these URLs from the WWW-Authenticate response and should not require them as manual configuration.

Troubleshooting

The client does not open realm authorization

• Confirm the client uses the realm-qualified /realm/<realm-public-id>/ai/mcp/... endpoint, not the direct /ai/mcp/... endpoint.
• Confirm realm OAuth is enabled and the client's exact CIMD URL is in allowed_clients.
• If the CIMD URL is unknown, follow Find an unknown client ID.
• Confirm the client supports protected-resource discovery, authorization-server discovery, and CIMD.

The client authenticates but cannot connect

• Confirm the client follows HTTP 307 while preserving the POST body and authorization.
• Confirm the realm and realm user are enabled.

Tools return permission errors

• Grant POST ai/mcp to the realm role or user.
• Grant the required HTTP methods on each downstream API section the tools must access.
• Check whether the target item belongs to a parent or sibling account outside the user's permitted hierarchy.

Limitations

All transport, capability, tool, credit, and protocol limitations documented for the corresponding flespi MCP servers also apply to their realm-wrapped endpoints. Realm MCP additionally requires a client compatible with realm OAuth discovery and the HTTP 307 redirect described above.