MCP Authentication

MCP servers support three authentication styles in Fabric Agents: none, bearer token, and OAuth. Set the mode with mcp.authType in the source's config.json.

none

Public MCP servers (including the built-in fabric-agents-docs) don't need credentials. The source connects immediately on enable.

{
  "mcp": {
    "url": "https://example.com/mcp",
    "authType": "none"
  }
}

bearer

The classic "paste an API token" flow. Fabric Agents stores the token in the OS keychain (or the encrypted credential store on Linux) and sends it as Authorization: Bearer <token> on every MCP request.

{
  "mcp": {
    "url": "https://mcp.example.com",
    "authType": "bearer"
  }
}

In the UI, the source shows a Connect button. Paste the token, save, and the source becomes usable. Editing the source later shows Reconnect — same flow, replaces the stored token.

Bearer tokens don't auto-refresh. If your provider issues short-lived tokens, consider using OAuth instead (if the server supports it) or rotating manually.

oauth

The full OAuth 2.0 dance, with automatic token refresh. This is what most hosted MCP servers use today.

{
  "mcp": {
    "url": "https://mcp.linear.app/mcp",
    "authType": "oauth"
  }
}

When you click Connect on an OAuth source, Fabric Agents:

1. Discovers the server's authorization metadata via RFC 9728 (/.well-known/oauth-authorization-server).
2. Dynamically registers as an OAuth client if the server supports RFC 7591. You don't need to pre-register an app — Fabric Agents does it on the fly.
3. Opens your browser to the authorization URL. You approve the connection.
4. Receives the authorization code at a local callback (desktop app) or at the stable relay URL https://agents.fabric.pro/auth/callback (Web UI and headless server setups).
5. Exchanges the code for an access token plus refresh token.
6. Stores everything in the credential store: access_token, refresh_token, expiresAt, and the clientId it registered with.

After this, you're done. The source just works.

Token refresh

Fabric Agents watches token expiry. When a token is within ~5 minutes of expiring, it refreshes automatically using the stored refresh token and clientId. You never have to re-authenticate unless the refresh token itself is revoked.

If refresh fails — usually because the user revoked the grant on the server side — the source goes back to "needs auth" and shows the Reconnect button.

Redirect URIs

• Desktop app: redirect URI is a short-lived localhost URL (http://127.0.0.1:<port>/callback). The OAuth server redirects to that URL; the desktop app picks up the code.
• Web UI / headless server: redirect URI is the stable public relay https://agents.fabric.pro/auth/callback. The relay unwraps a signed envelope and forwards the code back to your server. Your server's URL never has to be publicly reachable.

Where credentials are stored

The credential store holds three credential types for sources:

Config files (~/.fabric-agent/workspaces/{ws}/sources/{slug}/config.json) never contain tokens. They hold the authType and the server metadata, nothing secret. You can commit a workspace folder to a repo without leaking credentials.

Bearer fallback from OAuth

If authType: "oauth" is set but the server doesn't support OAuth discovery at its URL, Fabric Agents will try to fall back to bearer auth using any stored token. In practice this means a manually-pasted token still works on an "oauth" source while you debug the OAuth flow — useful during server development.

Revoking a source

• Disable (toggle in the sidebar) — keeps the config and credentials; the source just isn't available to sessions.
• Delete source — removes the config folder. Tokens stay in the credential store unless you also revoke them server-side; deleting the folder breaks the binding so no future session can use them.
• Revoke on the server — the provider (Linear, GitHub, etc.) has its own "Connected apps" list. Remove Fabric Agents there to invalidate the refresh token.

Related

• Connecting MCP servers — the config.json schema for each transport.
• Sources overview — scope, enable/disable, where configs live.
• APIs — REST API source auth (similar patterns, different config shape).