Connect an AI agent
Use this guide to connect an MCP-compatible AI client to FlowGuard so it can investigate request logs and manage rules and actions for one team or all your teams.
Choose your task
- Connect an AI client
- Choose one team or all your teams
- Try a request
- Review the available tools
- Let the agent change rules and actions
- Fix a connection or permission problem
Connect an AI client
Before you connect
Your AI client must support remote MCP servers and browser-based sign-in. Use this server URL:
Code
Connect a client
Look for MCP or integrations in your client's settings, then:
- Open the client's MCP or integrations settings.
- Add a remote MCP server with the URL above.
- Sign in with your Chief account.
- Under Select a team, choose the team the agent may use, or All my teams.
- Review the requested scopes and select Authorize.
FlowGuard asks for read access when you first connect. The agent can then search logs and inspect rules, actions, servers, and IP lists, but it cannot change anything.
Review the requested access
The authorization screen presents all requested scopes as one set. You must approve the full set or cancel the connection.
Choose one team or all your teams
The team you select in step 4 decides which FlowGuard data the agent can reach.
| Choice | What the agent can use |
|---|---|
| A single team | Only that team. The agent never has to pick a team. |
| All my teams | Every team you belong to, including teams you join later. The agent picks a team for each request. |
With All my teams, the agent gets the same scopes in every team. Name the team in your request, such as "In the Staging team, list the rules", so the agent does not have to guess. It should ask you when the team is unclear and tell you which team it used. Before you approve a rule or action change, check that the agent named the right team.
To switch between one team and all teams, reconnect the client and make a different choice.
What happens next
After connecting, give the client a specific task. For example:
- Summarize traffic to my servers over the last hour and point out anything unusual.
- Find requests that returned a
5xxstatus in the last 30 minutes. - Which countries and ASNs sent the most blocked requests today?
- List my rules in evaluation order and explain what each one does.
- Which of my teams received the most blocked requests today?
The last example only works with All my teams. Start with a short time range, such as the last hour, and widen it only when the agent finds too little. The agent can only find logs that the team still retains, so an empty result means no retained log matched, not that the traffic never happened.
Available tools
Your client may list every tool, but each tool only works when the connection has its required scope. A higher-level scope also works. For example, flowguard:rules:write covers flowguard:rules:read.
Teams
| Tool | Action | Required scope |
|---|---|---|
list-teams | List the teams the connection can use and mark your default team | None |
list-teams is only available to connections authorized for All my teams. These connections name a team on every other tool call. Your default team is a hint for the agent, not an automatic choice.
Request logs
| Tool | Action | Required scope |
|---|---|---|
summarize-traffic | Summarize request rates, top dimensions, and changes from the baseline | flowguard:logs:read |
list-log-fields | List the log fields and operators available to filters | flowguard:logs:read |
query-logs | Search retained request logs | flowguard:logs:read |
get-log-by-stream | Retrieve the log for a known stream ID | flowguard:logs:read |
get-log-window | Show the requests just before and after a known event | flowguard:logs:read |
Rules
| Tool | Action | Required scope |
|---|---|---|
get-rule-capabilities | List the supported conditions, matches, and action results | flowguard:rules:read |
list-rules | List rules in evaluation order | flowguard:rules:read |
get-rule | Retrieve one rule | flowguard:rules:read |
create-rule | Create a rule | flowguard:rules:write |
update-rule | Update a rule | flowguard:rules:write |
disable-rule | Disable a rule while keeping its conditions | flowguard:rules:write |
Actions
| Tool | Action | Required scope |
|---|---|---|
list-actions | List actions and how many rules use each one | flowguard:actions:read |
get-action | Retrieve one action | flowguard:actions:read |
create-action | Create an action | flowguard:actions:write |
update-action | Update an action | flowguard:actions:write |
Servers and IP lists
| Tool | Action | Required scope |
|---|---|---|
list-servers | List proxies and their configuration status | flowguard:servers:read |
list-ip-lists | List team and global IP lists that rules can use | flowguard:ip_lists:read |
The agent cannot delete rules or actions, add or remove servers, or edit IP lists. Use the FlowGuard dashboard or the REST API for those tasks.
Allow rule and action changes
When you ask the agent to create, update, or disable a rule or action, it needs flowguard:rules:write or flowguard:actions:write. Some clients ask you to approve the extra scope when the agent first needs it. If yours does not, reconnect the client and approve the write scopes.
Rule changes reach your proxies
FlowGuard sends saved rule changes to your team's proxies, where they affect live traffic. Updating an action changes every rule that uses it.
Before you let the agent continue with a write, check that it states:
- which requests the rule matches
- which action it applies
- which servers it targets
- what effect you should expect on traffic
After the change, ask the agent to read the rule again and check the proxies' configuration status. A disabled rule stays in your rule list without an action, so you can enable it again later.
Manage the connection
Change permissions
Start with read access. Approve write scopes only when you want the agent to change rules or actions, and reconnect without them when it no longer needs that access.
See FlowGuard API scopes for the full scope hierarchy.
Choose MCP or REST
Use MCP when an AI client needs to choose and call FlowGuard tools. Use the REST API for application code, fixed workflows, or operations that the MCP server does not expose.
Troubleshooting
Why can't the client connect?
Confirm that the client supports remote MCP servers and browser-based authorization. Copy the server URL exactly, then reconnect and complete the Chief sign-in flow.
Why does a tool report insufficient scope?
The connection does not have the tool's required scope. Compare the tool with the tables above, then approve the additional scope when your client asks, or reconnect the client and approve it.
Why can't the agent find any logs?
Ask for a shorter, more recent time range or fewer filters. Logs older than your team's retention period are no longer available. You can compare the result with the Stream.
Why can't the agent see one of my teams?
The connection is limited to the team you selected when you connected. Reconnect the client and choose that team or All my teams. With All my teams, the agent can only use teams you are a member of.
Why did the agent use the wrong team?
With All my teams, the agent picks a team for each request. Name the team in your request and ask the agent which team it used. If you only work in one team, reconnect and select that team instead.
Why does the agent report too many requests?
FlowGuard limits how often a connection can call the server and query logs. Wait a minute, then ask the agent to continue with a narrower query.
Why doesn't a rule change affect traffic yet?
Ask the agent to check the proxies' configuration status with list-servers. Also check earlier rules in the evaluation order, because an earlier rule may already handle the request.
Why does the authorization screen request unexpected access?
Cancel the connection and review which tools or integration the client is trying to enable. FlowGuard approves or rejects the requested scopes as one set.