Skip to main content

MCP Server

Toggly exposes a remote Model Context Protocol server so AI agents can manage feature flags.

Endpoint: https://app.toggly.io/mcp

Connect from Claude Code, Cursor, Codex, VS Code, Gemini CLI, Windsurf, Claude Desktop, or ChatGPT. The server uses Streamable HTTP. Authentication is OAuth by default (RFC 9728 discovery) for interactive clients. For headless agents (CI, Cloud Agents, cron), create an MCP access token on AI Agent Access and send Authorization: Bearer tog_mcp_….

Enable MCP in Toggly​

  1. Sign in to app.toggly.io.
  2. Open AI Agent Access (MCP) in the dashboard.
  3. Connect from your client with OAuth, or create an access token for headless use. Toggly enables MCP for your user on first successful OAuth (or when you create a token if MCP is already enabled).
  4. On first OAuth connect, choose which applications the agent may access and which permissions it gets (view apps, toggle flags, metrics, create flags, and so on). Token scopes are capped by those same AI Agent Permissions.

All MCP actions use your user permissions (intersected with token scopes when using a PAT) and are written to the audit log.

Authentication​

Most desktop and IDE clients complete a browser OAuth flow. You do not put a secret in config for OAuth.

Access tokens (headless / PAT)​

  1. On AI Agent Access, create an access token (name, scopes or “everything I can access”, expiry).
  2. Copy the plaintext once (tog_mcp_…). Store it in an environment variable or secret store — never commit it.
  3. Send it on every MCP request:
Authorization: Bearer tog_mcp_YOUR_TOKEN

Effective permissions = token scopes ∩ your current AI Agent Permissions. Revoking the token or shrinking your permissions immediately reduces access.

Example Cursor .cursor/mcp.json using an env var (replace nothing in the URL):

{
  "mcpServers": {
    "Toggly": {
      "url": "https://app.toggly.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TOGGLY_MCP_TOKEN}"
      }
    }
  }
}

Set TOGGLY_MCP_TOKEN in the environment or agent secret store. Prefer OAuth in interactive Cursor when a browser is available.

Connect a client​

Replace nothing in the URL. Every client talks to the same public endpoint.

Claude Code​

claude mcp add --transport http toggly https://app.toggly.io/mcp

Then run /mcp, select Toggly, and complete the browser OAuth flow. For headless use, add an Authorization header with your access token instead of OAuth.

Cursor​

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "Toggly": {
      "url": "https://app.toggly.io/mcp"
    }
  }
}

Enable Toggly in Settings → Tools & MCP, choose Authenticate, and finish OAuth in the browser. For Cloud Agents or other headless setups, use the access-token headers example above.

Codex​

[mcp_servers.toggly]
url = "https://app.toggly.io/mcp"

Restart Codex if prompted, then authenticate beside Toggly. For headless Codex, pass an Authorization Bearer header with an MCP access token.

VS Code / GitHub Copilot​

Add to .vscode/mcp.json:

{
  "servers": {
    "Toggly": {
      "type": "http",
      "url": "https://app.toggly.io/mcp"
    }
  }
}

Start the server from the MCP Servers view and complete the OAuth prompt. For headless use, add a Bearer header from a secret or VS Code inputs prompt.

Gemini CLI​

gemini mcp add --transport http toggly https://app.toggly.io/mcp

Run /mcp auth toggly and complete OAuth. Manual config must use "httpUrl", not "url" (that key is SSE).

Windsurf​

{
  "mcpServers": {
    "Toggly": {
      "serverUrl": "https://app.toggly.io/mcp"
    }
  }
}

Authenticate from Cascade → MCP Servers. Prefer OAuth interactively; use an access token for headless agents.

Claude Desktop​

In Settings → Connectors, add a custom connector named Toggly with URL https://app.toggly.io/mcp. Remote servers are connectors, not claude_desktop_config.json entries. Team and Enterprise workspaces need an owner to add the connector. Prefer OAuth for Claude connectors.

ChatGPT​

In Settings → Apps, create an app named Toggly and enter https://app.toggly.io/mcp. Choose OAuth, scan tools, and authorize. Custom MCP apps require Business or Enterprise/Edu; a workspace admin may need to enable developer mode.

What agents can do​

With the permissions you grant, agents can:

  • List teams and applications
  • Read application details, environments, and feature status
  • Enable, disable, or change feature filters
  • Create, update, and delete feature flags
  • Read audit history for a feature or environment

Troubleshooting​

  • Client says the server is unreachable: MCP clients follow the WWW-Authenticate resource_metadata URL (RFC 9728). That URL must be https://app.toggly.io/.well-known/oauth-protected-resource/mcp, not localhost. If you still see localhost, the public origin is misconfigured on the server.
  • OAuth loop or consent every few minutes: Confirm the client requested offline_access so it can refresh tokens.
  • 401 with an access token: Confirm the token starts with tog_mcp_, is not expired or revoked, MCP is still enabled for your user, and you still belong to the token’s workspace.
  • Permission errors: Re-run the in-app permission selection for that OAuth client, grant the missing MCP permission on AI Agent Access, or mint a token with broader scopes (still capped by your user settings).

See also​