# Multi-agent isolation

Run several agents on one platform with credentials, sessions, limits and audit that never mix.

One agent is easy - the questions start with the second one: whether it can replay the first one's session, whether it shares the first one's rate limit and which tools are visible to it. The three agents below run against two [MCP gateways](https://zato.io/docs/ai/mcp/index.html), and each answer is a mechanism the platform enforces.

## The layout {#the-layout}

Three agents, three credentials, two gateways - support agents share the support tools, the billing agent alone reaches the billing ones:

```yaml
security:
  - name: agent.support.alpha
    type: apikey
    username: support-alpha
    password: Zato_Enmasse_Env.Support_Alpha_Key

  - name: agent.support.beta
    type: apikey
    username: support-beta
    password: Zato_Enmasse_Env.Support_Beta_Key

  - name: agent.billing
    type: apikey
    username: billing-agent
    password: Zato_Enmasse_Env.Billing_Agent_Key

groups:
  - name: support-agents
    members:
      - agent.support.alpha
      - agent.support.beta

  - name: billing-agents
    members:
      - agent.billing

mcp_gateway:
  - name: support
    url_path: /mcp/support
    services:
      - example.support.get-ticket
      - example.support.list-tickets
    security_groups:
      - support-agents

  - name: billing
    url_path: /mcp/billing
    services:
      - example.billing.get-invoice
      - example.billing.find-invoices
    security_groups:
      - billing-agents
```

One credential per agent is the rule everything below builds on - a shared key is one identity, and one identity cannot be isolated from itself.

## Tool visibility {#tool-visibility}

Tool visibility is per gateway - every agent admitted to a gateway can list all of its tools. Restricting which tools an agent can list therefore means separate gateways, not separate credentials on one gateway:

| Agent | `tools/list` on `/mcp/support` | `tools/list` on `/mcp/billing` |
| --- | --- | --- |
| `agent.support.alpha` | The two support tools | HTTP 403 - not in `billing-agents` |
| `agent.support.beta` | The two support tools | HTTP 403 |
| `agent.billing` | HTTP 403 - not in `support-agents` | The two billing tools |

The refusal happens at [authentication](https://zato.io/docs/ai/mcp/security.html), before any MCP processing - an agent outside a gateway's groups never learns what the gateway serves, not even the tool names.

## Session isolation {#session-isolation}

If `agent.support.beta` somehow obtained alpha's `Mcp-Session-Id` - a leaked log, a shared proxy - replaying it is refused with HTTP 400, because [sessions are bound to the identity](https://zato.io/docs/ai/mcp/index.html#endpoint-behavior) that created them, and each identity has its own budget of live sessions per gateway.

## Rate limits per credential {#rate-limits-per-credential}

Alpha caught in a retry loop hits its own ceiling while beta's traffic flows on untouched - [limits are per identity](https://zato.io/docs/ai/mcp/rate-limits.html), which is also why an agent needing an independent budget needs its own credential, and the layout above already gives it one.

## Audit per identity {#audit-per-identity}

Every [audit log](https://zato.io/docs/ai/mcp/audit-log.html) event names the identity the agent authenticated with, so listing everything the billing agent did yesterday is a filter, not an investigation.

## Failure behavior {#failure-behavior}

Offboarding one agent is one operation - remove its credential from the group, or delete the definition altogether. From that moment its requests answer with HTTP 403 and an `auth-failed` audit event, its live sessions are unusable since the identity no longer resolves, and no other agent is affected. There is no shared secret to rotate, because nothing was shared.

## See also {#see-also}

- [MCP gateway security](https://zato.io/docs/ai/mcp/security.html) - Credentials, groups and how identities resolve
- [MCP rate limits](https://zato.io/docs/ai/mcp/rate-limits.html) - Per-identity traffic caps
- [Secured APIs as tools](https://zato.io/docs/ai/examples/secured-apis-as-tools.html) - Agent credentials separated from backend credentials