Connect an agent over MCP

Fanout serves MCP at /mcp. It is the intended way for an agent to read an instance: the tools return the same typed results the browser client and the HTTP API use, so what an agent tells you matches what the dashboards show.

Build and refine dashboards covers schema discovery, panel previews, targeted edits and saved-version restore through chat or MCP.

Set the public URL first

export FANOUT_PUBLIC_URL=https://fanout.example.com

Fanout derives the MCP resource URI from this — the canonical, externally reachable origin that clients are issued tokens against. It must be HTTPS, and it must stay stable across restarts: tokens carry the derived resource as their audience, so changing it invalidates every one already issued.

Getting this wrong is the most common failure. A client discovers, registers and receives a token, and then every call is rejected because the audience does not match the resource it is calling. Set it before connecting anything.

The resource is derived from FANOUT_PUBLIC_URL; there is no separate MCP public-origin setting. An unrecognised FANOUT_-prefixed variable is a startup error rather than something ignored.

Set FANOUT_MCP_ENABLED=false to turn the endpoint off entirely; it defaults to true.

What the client does

Fanout implements the standard remote-MCP OAuth flow, so a compliant client needs only the URL:

1. Discovers the endpoints from /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.
2. Registers itself at /oauth/register — dynamic client registration, so nothing is pre-provisioned by hand.
3. Obtains a token from /oauth/token, bound to the resource URI above.

You authorize it in the browser as yourself, which ties the agent to your account without delegating your first-party account role.

Scopes

Scope	Grants
telemetry:read	The read-only observability tools
dashboard:manage	list_dashboards, get_dashboard, create_dashboard, replace_dashboard, edit_dashboard, list_dashboard_versions, and restore_dashboard_version

An agent holding only telemetry:read can investigate but cannot manage a dashboard.

The MCP tool catalog provides list_dashboards, get_dashboard, create_dashboard, replace_dashboard, edit_dashboard, list_dashboard_versions, and restore_dashboard_version. Restore requires an explicit user request and appends the selected historical spec as a new saved version with a normal save receipt. Deletion is available in Fanout’s dashboard API; there is no MCP delete tool.

What the agent can and cannot do

It acts on your behalf, but its delegated authority comes from the scopes you approve rather than your account role. Fanout also checks that your current account capabilities still permit those scopes. Two consequences:

• Dashboard tools are owner-scoped. An agent can manage your dashboards and cannot touch anyone else’s.
• agent:run is not involved here. That capability gates Fanout’s own chat investigator; an external MCP client is a separate path.

There is no tool that writes telemetry, edits configuration, manages users or changes alert rules. That is the whole envelope, deliberately.

Behind a proxy

If TLS terminates at a reverse proxy, FANOUT_PUBLIC_URL must be the externally visible HTTPS origin rather than the internal address Fanout is listening on. Terminate TLS covers the rest of that setup.

Checking it

/.well-known/oauth-protected-resource is unauthenticated, so a plain fetch tells you whether discovery is answering and what resource it advertises:

curl -s https://fanout.example.com/.well-known/oauth-protected-resource

If the resource in that document is not the URL your client is calling, fix FANOUT_PUBLIC_URL before debugging anything else.