Running an Agent Fleet: One Scoped Key per Agent

Choose a credential boundary you can actually revoke

Suppose six review agents run in separate VMs while a release agent runs in CI. If all seven use the same key, the credential record cannot tell you which VM requested a release operation. Disabling that credential also stops all seven consumers. Different agent names in prompts do not change that relationship.

Issue a distinct key to each independently managed deployment. If three replicas must be investigated or stopped separately, give each replica its own key. For disposable jobs, make issuance and revocation part of the job lifecycle where your credential service supports it. A model-generated subagent sharing its parent's process is not automatically a separate credential boundary.

Maintain an inventory mapping the non-secret key ID to an agent label, human owner, environment, VM or job identifier, allowed sources, permissions, issue date and planned retirement. A label such as review-vm-03 is useful inventory metadata; authentication must still depend on the actual credential. Copying its key into another VM destroys the one-to-one mapping.

Turn the fleet's job list into explicit grants

Write down what each deployment needs before creating its key. For this example fleet, use three profiles:

• Review VM: read repository content and engineering documentation; no release system access and no remote mutations.
• Release CI agent: read release inputs and perform approved release operations in staging; no production access or finance source.
• Documentation agent: read engineering documentation; no repository or release access, and no permission to change shared agent memory.

These are proposed policies, not universal MCP scope names. Translate them into the credential provider's actual source and permission controls. If a provider cannot distinguish staging from production within one source, use separately restricted upstream credentials or separate connections. A source allowlist alone cannot express every repository, row or environment boundary.

The MCP authorization specification recommends requesting only scopes needed for intended operations and requires OAuth token audience validation. Use a token intended for the MCP endpoint rather than passing an unrelated upstream token through it. MCP's versioned ToolAnnotations schema also warns that annotations are hints: readOnlyHint is not proof of implementation behavior. Review the upstream and enforce its underlying privileges. For the permission model, see scoping API keys for agents.

Share the MCP configuration and inject different secrets

Claude Code documents environment-variable expansion in .mcp.json, including HTTP authentication headers. This configuration uses an illustrative endpoint; replace its URL with your gateway's endpoint:

{
  "mcpServers": {
    "company-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FLEET_MCP_KEY}"
      }
    }
  }
}

Deliver the same file to every review VM, but have the launcher inject a different FLEET_MCP_KEY into each process environment from its assigned secret. Inject the release agent's credential only into the release job. Keep secret values out of the image, repository, launch-command arguments and provisioning output. Environment injection is a delivery mechanism; it does not stop code inside that runtime from reading the credential.

Make the launcher reject a missing secret before starting Claude Code. Anthropic documents that an unset variable without a default can remain unexpanded with a warning, so loading the configuration is not an authentication test. Verify an allowed call after launch. Keep the deployment details in keeping secrets out of agent configurations.

Test the boundaries with two agents online

Run a deterministic authorization check before admitting a deployment to the fleet. Use a disposable source with known records and mutations, and exercise the service directly through a test client. Asking the model to avoid a forbidden tool does not test whether the service rejects it.

1. Using the review key, read a known repository fixture and confirm its expected content.
2. Attempt a read from the release source with that same key. Require a permission denial and confirm that no protected content was returned.
3. Attempt a mutation against the disposable repository fixture. Require rejection and independently verify that the fixture did not change.
4. Using a separate staging release key, perform the intended staging operation and confirm its result. Attempt the equivalent production operation and require rejection.
5. Revoke the review key. Retry its previously successful read through the existing client and then a fresh client; both must fail within the service's documented revocation behavior.
6. Repeat the staging agent's allowed operation. It must still work, demonstrating that revocation did not disable its credential.

Check failures at the execution boundary even if discovery hides forbidden tools. Keep observed results with the inventory entry, and rerun these checks when a profile gains a source or write permission.

Make attribution survive retries and replacement VMs

Require your gateway's audit events to include a non-secret credential identifier alongside source, tool, outcome, duration and timestamp. Correlate that identifier with the VM or CI run in your inventory. Record deployment and permission changes so an investigation can reconstruct what the key could reach when a call occurred.

Treat caller-supplied agent names and run IDs as correlation data. A stolen key can submit the same names. The authenticated key ID identifies the credential presented; it does not prove which binary, model or physical machine used it. Investigate unexpected simultaneous use from different deployments, and check whether provisioning accidentally distributed one secret twice.

Never record bearer values to improve attribution. Use the credential service's identifier, and keep authorization headers out of application traces and support bundles. Review fleet-specific exceptions: a review key making release attempts, a retired VM still calling tools, or a staging deployment repeatedly requesting production access. After replacing a VM, reconcile the retired key before marking its replacement healthy.

Running separate agent keys with SPYN3

SPYN3 provides one MCP endpoint per workspace at https://api.spyn3.com/agent/mcp. An admin or owner can create a separate key for each deployment, limited to chosen sources. call:tools permits upstream-marked read-only tools; unmarked tools count as writes and require call:write_tools. Memory writes separately require write:memory. Upstream credentials stay envelope-encrypted in the workspace and never reach the agent. Revoking a key in the dashboard takes effect on the next call. SPYN3 audit-logs every proxied tool call with source, tool, outcome and duration.

Retire credentials as deliberately as you provision them

For routine rotation, create a replacement with the same reviewed grants, update only its assigned runtime, confirm an allowed call, and revoke the old key. Keep any overlap brief and recorded. If exposure is suspected, revoke first; restoring that agent's availability comes after removing the suspect credential's access.

With OAuth-based deployments, check how the provider couples access tokens, refresh tokens and authorization grants. RFC 7009 allows revoking one token to invalidate related tokens and discusses propagation delays. Different access-token strings therefore do not automatically provide independent revocation. Test the provider's actual behavior before treating two OAuth sessions as separately stoppable fleet members.

Include failed startup, cancelled CI jobs and abandoned VMs in cleanup. A destroyed sandbox leaves a credential usable wherever else it was copied unless the service invalidates it. Reconcile active deployment records against issued keys and investigate unmatched entries. Finish a retirement by checking that the old credential fails and an unrelated agent still succeeds. Use central agent-access revocation to turn that check into an operating procedure.