Connect Formal MCP - Formal Documentation

Overview

is Formal’s hosted MCP server at https://mcp.formal.ai/mcp. https://api.formal.ai/mcp still reaches this server. The server stays current with shipped product behavior. It can search the API reference and query the state of your organization. Clients you approve for write can also change it.

This is Formal’s hosted server. It is not an MCP resource. MCP resources proxy other MCP traffic through a Connector.

What Formal MCP can do

Capability	Use it to
Search the API reference	Find the current RPC, fields, and validation rules.
Search for a keyword	Resolve a name, email, hostname, or ID in your org.
Query organization state	Read resources, policies, connectors, and other objects you can already see.
Read access logs	Inspect recent traffic and group it by user, resource, or policy.
Change organization state	Create, update, and delete objects. Needs write access.

Calls run as the authenticated identity. The client never sees or changes more than you can in the Control Plane.

Connect with OAuth

Clients that support MCP authorization, such as Claude and Cursor, sign you in to Formal MCP without an API key. Add the server URL and the client opens a browser to approve it.

Add the server to your client

Point the client at https://mcp.formal.ai/mcp with no headers.

Claude Code
Cursor

claude mcp add formal https://mcp.formal.ai/mcp --transport http

{
  "mcpServers": {
    "formal": {
      "url": "https://mcp.formal.ai/mcp"
    }
  }
}

Approve the client

The client opens Formal in your browser. Check the application name, where it is published, and where it returns. Choose its access, then click Approve.

The client acts as you. As with an API key, it reaches only the public API. Your Permissions apply to every call and can single out OAuth clients with input.user.oauth. Each call is logged with the client that made it. Authorized apps, in your account menu in the Catalog, lists each client and its access: Read, Write, or Custom for a choice per app. Revoke a client there to stop it at once. Admins see every user’s clients under Authorized apps on the OAuth page.

Access per app

Formal is made of apps, named as in the Control Plane, such as Policies or Resources. A client gets one of these on each app:

Access	The client can
No access	Nothing. Formal refuses every call to the app, and leaves out tools that only use it, such as log search without Logs.
Read	Read the app’s objects. Formal refuses any call with side effects, even ones your role allows.
Write	Also create, update, and delete them with the `mutate_api` tool.

When you approve a client, choose Read for read on every app, Write for write on every app that has changes, or Choose per app. Read is selected by default, even when the client asks for more. To change a client’s access, revoke it and connect it again. Some changes stay out of reach with any access, because they could widen the client’s own access, keep it working after you revoke it, or let it act as another identity, or because they are emergency controls for the whole organization. Make them yourself in the Control Plane. They include:

Permissions, group membership, renaming or deleting groups, and unblocking users
Creating signing keys, and creating or changing OIDC integrations and OAuth clients
Creating or changing hooks, policy data loaders, or native user credentials, which run code or act as another identity
Forcing every user in the organization to sign in again

Changes a client makes stay after you revoke it. For example, a user it creates can still sign in, a log destination it adds keeps receiving logs, and a workflow it builds keeps running. To narrow what clients can change, see Permissions.

OAuth is available on deployments that publish Formal MCP on its own host, such as mcp.formal.ai. Self-hosted deployments set MCP_PUBLIC_BASE_URL and OAUTH_PUBLIC_BASE_URL to enable it.

Connect with an API key

Use an API key for clients without MCP authorization support, and for scripts. With an API key, Formal MCP only reads. Send an API key in the x-api-key header, as for the rest of the Formal API. See API authentication.

Create an API key

Go to API Keys and click Create API Key. Copy the key once.

Add the server to your client

Point the client at https://mcp.formal.ai/mcp and send the key on every request.

Claude Code
Cursor
Other clients

claude mcp add formal https://mcp.formal.ai/mcp \
  --header "x-api-key: <YOUR_API_KEY>" \
  --transport http

{
  "mcpServers": {
    "formal": {
      "url": "https://mcp.formal.ai/mcp",
      "headers": {
        "x-api-key": "<YOUR_API_KEY>"
      }
    }
  }
}

Use HTTP transport against https://mcp.formal.ai/mcp. Send x-api-key: <YOUR_API_KEY> on each request. The same header works in a CLI flag or a config file.

Verify the connection

Ask the client to list your connectors. You should get live results from your organization.

curl -s -X POST https://mcp.formal.ai/mcp \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response lists the read-only tools above.

Treat the API key like any other Formal secret. Do not commit it to source control or share it in a public prompt.

​Overview

​What Formal MCP can do

​Connect with OAuth

​Access per app

​Connect with an API key

Overview

What Formal MCP can do

Connect with OAuth

Access per app

Connect with an API key