Connect an AI agent (MCP)
Let an MCP-capable agent read and change your flags through the remote Toggld MCP server.
The Model Context Protocol (MCP) lets an AI agent discover tools and call them. Toggld runs a remote MCP server that gives your agent tools for flags, segments, environments, credentials, the audit log, analytics, and evaluation.
Your agent signs in through OAuth in your browser. You do not copy a session cookie or a management key into the agent.
MCP server URL: https://mcp.toggld.io/
Requirements
Your MCP client must support:
- Remote servers over Streamable HTTP.
- OAuth discovery and public client registration.
- The authorization code flow with S256 PKCE.
Connect your agent
- In your MCP client, add a remote MCP server with the URL
https://mcp.toggld.io/. In the dashboard, Connect your AI shows the same URL with a copy button. - Connect the server. Your client opens the Toggld sign-in page.
- Sign in with GitHub, a passkey, or an email link.
- On the Connect your agent page, check the callback address and the requested permissions.
- Select a workspace.
- Choose a permission level.
- Select Allow access.
Continue only if you started the connection yourself.
Changed from /mcp
If your client uses an older address that ends in /mcp, change it to https://mcp.toggld.io/, reconnect, and approve access again. Existing tokens work only with the address they were issued for.
One workspace per connection
Each connection covers one workspace. To give an agent access to another workspace, connect again and select that workspace.
The server checks your current workspace membership before each tool call. If you leave the workspace or someone removes you, the connection stops working.
Permissions
The consent page offers three permission levels:
| Permission level | Scopes | The agent can |
|---|---|---|
| Read only | management:read | Read flags, environments, segments, audit events, and analytics. Evaluate flags. |
| Read and change resources | management:read, management:write | Also create, change, and delete flags, segments, and environments. |
| Read, change resources, and create or revoke API keys | management:read, management:write, keys:write | Also create and revoke API keys. The agent receives each new secret key. |
The agent requests all three scopes when it connects. On the consent page you can grant less than it asked for, but never more.
Your workspace role also limits the agent:
- Readers can grant read-only access. Readers' agents cannot list API keys or public tokens.
- Owners, admins, and members can grant every level.
- Members' agents cannot change environments or create management keys, because members cannot do that either. They can create server SDK keys.
See Members and roles.
Tools
The server has 28 tools. Your client discovers each tool's input schema and required permissions.
| Area | Tools | Permission |
|---|---|---|
| Workspace | get_workspace | Read |
| Flags | list_flags, list_tags, get_flag | Read |
| Flags | create_flag, replace_flag, update_flag, delete_flag | Change |
| Segments | list_segments, get_segment, list_segment_members | Read |
| Segments | create_segment, update_segment, delete_segment, update_segment_members | Change |
| Environments | list_environments | Read |
| Environments | create_environment, update_environment, delete_environment, reorder_environments | Change |
| Credentials | list_api_keys, list_public_tokens | Read, and a role other than reader |
| Credentials | create_api_key, revoke_api_key | API keys |
| Audit and analytics | list_audit_events, get_flag_analytics | Read |
| Evaluation | evaluate_flag, evaluate_flags | Read |
The catalog covers every public management operation, single and bulk evaluation, and the authorized workspace. It does not include tenant administration, identity administration, or telemetry ingestion.
Environments
Flag reads, flag writes, analytics, and evaluation tools require an environment argument with an environment key or ID. There is no default environment. The agent can call list_environments to find one. create_api_key also requires environment, the key of the environment that the new key belongs to.
list_environments returns the environments in order. reorder_environments sets a new order and takes every environment ID exactly once. create_environment adds the environment at the end of the order.
Flag values, the enabled state, and targeting rules belong to the selected environment. Names, descriptions, tags, and metadata are shared by every environment. delete_flag removes a flag from every environment. Segments apply in every environment.
Safe updates
Ask your agent to read a flag before it changes it. The agent passes the flag's version as expectedVersion in update_flag (inside patch) or replace_flag (inside flag). If someone changed the flag in the meantime, the tool returns a conflict with API status 409, and the agent must read the flag again.
API keys from agents
create_api_key returns the secret key once. Store it in a secret store, and keep it out of shared conversations. Revoking an API key stops every application that uses it. Revoking the agent's connection does not revoke API keys that the agent created.
Activity and limits
The agent acts as you. Its changes appear in the audit log with your user as the actor.
- The server accepts one JSON message per
POST, up to 1 MiB. - Rate limits return HTTP 429 with
Retry-After: 300 requests per minute per IP address, and 120 tool requests per minute per user. Tool calls also count against the workspace's API rate limits.
Revoke a connection
- Open Account and security in the dashboard at toggld.io/account.
- Find the connection under Connected agents.
- Select Revoke agent access.
Revocation blocks future tool calls and token refreshes. It does not undo changes that the agent already saved.
Connections also expire on their own:
- Access tokens expire after one hour. The client refreshes them with its latest refresh token.
- A connection expires after thirty days.
- If anyone reuses a consumed authorization code or refresh token, Toggld revokes the connection.
Self-hosted installations
For a self-hosted Toggld installation, use the root URL of your MCP server, with a trailing slash, instead of https://mcp.toggld.io/. The sign-in and consent steps are the same.