Skip to main content

Agent identities

Give every autonomous agent its own identity in MintMCP: its own credential, its own tool access, and its own audit trail, separate from the human who created it.

Organizations adopting autonomous agents (CI jobs, scheduled summarizers, on-call triage bots, monitoring agents) have historically run them on whichever human's API key was lying around. That collapses the audit log (every action the agent takes looks like that human), over-privileges the agent (it inherits everything the human can do), and makes rotation painful (revoking the key breaks the human too). As agents multiply, so does the blast radius of every borrowed credential.

An agent identity fixes this by treating the agent as a first-class subject: a non-human principal with a name, a policy, and credentials of its own.

For a complete worked example (creating an agent identity, restricting its tools, minting a key, and connecting it to Claude in Slack), see Connect Claude Tag to MintMCP.

What an agent identity is​

An agent identity is a named, org-scoped principal created by an admin. Each agent has:

  • A name and optional description ("nightly deploy bot", "Slack triage agent")
  • An identity record that makes the agent a first-class subject in MintMCP's authorization model: the same model used for human users, so rules, middleware, audit, and identity forwarding already know what to do with it
  • Credentials for authenticating to the gateway (see How agents authenticate), plus its own downstream credentials where needed
  • An audit trail attributing every tool call to the agent, separately from any human user

An agent is not a human user: it can't log in through SSO, browse the MCP Store, or complete interactive OAuth on its own. That distinction shapes the credential model below.

The agent's MCP​

Each agent identity carries its own MCP: a Virtual MCP (VMCP) scoped to that agent instead of offered to human members. It has the same shape as any other VMCP: one endpoint, one access policy, one tool-curation surface, and one audit stream. But its access policy authorizes only that agent, which means you bind the MCP directly to the agent identity instead of attaching groups or users.

This gives you:

  • Purpose-built toolsets. Curate the agent's MCP to exactly what the workflow needs. A deploy agent gets deploy tools; a log-summarizer gets log-reading tools.
  • Independent rotation. Rotating the agent's credential doesn't affect any human, and deleting its MCP takes the agent down and nothing else.
  • Clean audit. Every call is attributed to the agent, with the admin who provisioned it recorded separately as the creator.

Creating an agent identity is a single admin flow: name the agent, pick the connectors, curate the tool set, issue credentials.

Works with​

Any agent platform that can send a bearer token or complete an OAuth client-credentials exchange can connect to an agent identity's MCP. Platforms teams commonly connect:

  • Claude Tag: Claude in a Slack channel, authenticating with an agent API key
  • Claude Managed Agent
  • ChatGPT Workspace Agents
  • OpenClaw
  • Hermes
  • Cursor Cloud Agents: headless coding agents connecting over M2M credentials
  • Coworker Agents: MintMCP-hosted agents get an identity automatically when you connect a VMCP

How agents authenticate​

Agents authenticate to the gateway with machine-to-machine (M2M) credentials. Two mechanisms are supported:

MechanismHow it worksUse when
Agent bearer keysThe agent presents a minted key directly on every requestSimplest path, and the default for most new agents
M2M tokensA client ID and secret are exchanged for short-lived access tokensMore secure, and the choice when the agent runtime can handle a token exchange (CI platforms, standing services)

Agent bearer keys​

An admin mints one or more bearer keys against the agent's MCP, and the agent presents the key in Authorization: Bearer … on every gateway request. Each key has an optional name and expiry, and can be revoked individually without affecting other keys on the same agent. See bearer keys for minting and managing keys.

M2M tokens​

M2M tokens are the more secure option: the long-lived secret stays out of every MCP request, and every token exchange is audited. For agents that speak OAuth 2.0 client credentials (many CI platforms and standing services do), MintMCP mints a client ID and client secret scoped to a specific agent identity. The agent POSTs to its MCP's token endpoint with grant_type=client_credentials, receives a short-lived access token, and uses it on subsequent MCP calls:

curl -X POST "https://app.mintmcp.com/o/<org-slug>/s/<server-slug>/m2m/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>"

The token endpoint comes in two shapes, .../o/<org-slug>/s/<server-slug>/m2m/token and .../s/<gateway-id>/m2m/token, so copy the exact one shown alongside your client credentials in the admin UI rather than deriving it.

Client secrets rotate without invalidating live access tokens, so you can roll a secret on your own schedule without a hard cutover. See M2M tokens for the full flow, secret rotation, scoping, and the token-exchange audit events.

Scope and permissions​

Agent identities sit in the same access-control model as humans, with a deliberately narrower scope surface:

  • Scoped MCPs, not roles. An agent sees exactly the MCP (or MCPs) created for it, and no more. Agents don't accumulate grants the way humans do.
  • Rules and middleware apply. Every rule and gateway middleware attached to the agent MCP's connectors runs on the agent's calls just as it does on a human's.
  • No admin escalation. Agents can't call the Admin MCP, change rules, or manage other agents, so they get only the tools curated inside their MCP.

Nothing here introduces a new permission model. An agent is a principal like any user, the MCP you build for it defines what it can reach, and tool curation narrows that further, so your existing access reviews and audit queries treat agents the same way they treat people.

Downstream credentials​

Per-user OAuth assumes a human can complete an interactive consent flow (sign in, click "Allow"), and that's not available to an agent.

Credential typeHow it's configuredUse when
Shared credentials (default)An admin configures the credential once per connector (service account, API key, or org-wide OAuth token)Most agent workflows
Agent-owned credentialsAn admin completes the OAuth flow on the agent's behalf, or attaches a per-agent bearer credentialThe connector genuinely needs per-agent credentials

Shared credentials are the default. Most agent workflows should use shared credentials on each connector in their MCP: the admin configures the credential once, the agent uses it for every call, and the MCP's access policy authorizes the agent to use it.

Agent-owned credentials are available when a connector genuinely needs them: an agent with its own GitHub service account, or its own Slack token. An admin completes the interactive OAuth flow on the agent's behalf at setup time, via an "act as this agent" mode in the admin UI, and MintMCP stores the resulting token against the agent. Bearer credentials can likewise be attached per-agent.

Identity forwarding. For shared-credential connectors, the gateway can forward caller identity downstream: X-MintMCP-User-Email for remote MCPs, MINTMCP_USER_EMAIL for hosted connectors. When the caller is an agent, the forwarded value is the agent's identity email, set in the Identity email field on the agent MCP's Credentials tab. New agents get a default derived from the agent's name at your organization's verified domain, and you can change it to match a real upstream account or clear it to forward nothing. Remote connectors still require the per-connector opt-in, and cooperating upstreams can use the forwarded email to distinguish agent traffic from human traffic in their own logs.

Rule of thumb: if the agent has a good reason to hold its own credential on a given connector, give it one; otherwise use the shared credential. Don't reuse a human admin's personal credential.

Common uses​

  • CI running deploys. A GitHub Actions workflow calls MintMCP to restart a hosted connector, flip a feature flag, or annotate a deploy.
  • Scheduled summarizers. A nightly job reads logs, synthesizes a summary, and posts to a channel.
  • On-call triage bot. An always-on agent reads alerts, correlates with monitoring, and opens tickets, and the audit log cleanly distinguishes its calls from the humans who later work the incident.
  • Monitoring and inventory agents. Periodic enumeration, drift detection, read-only tools.
  • Background coding agents. Cursor background agents authenticate through agent identities. See Set up Cursor.
  • Server-side agent platforms. Custom agents (frameworks, internal tools) that call MintMCP from server code rather than an interactive session.

Each maps cleanly onto "one agent identity, one narrow MCP, one M2M credential."

Agents hosted on MintMCP get identities automatically: when you connect a VMCP to a Coworker Agent, MintMCP mints a dedicated key for the agent, so every call it makes flows through the gateway under the agent's own identity.

Lifecycle​

  • Create. An admin with server-management permission creates the agent, attaches connectors, and issues credentials.
  • Configure downstream credentials. Prefer shared credentials; where agent-owned credentials are required, the admin configures them while acting as the agent.
  • Rotate. Bearer keys and M2M client secrets rotate independently: mint new, update the agent runtime, revoke old.
  • Revoke. Deleting a bearer key stops the next request made with it immediately. Revoking an M2M client secret blocks new token exchanges, though access tokens already issued from it keep working until they expire. Deleting the agent removes all its credentials and downstream authorizations at once.
  • Audit. Every call is attributed to the agent in the audit log, with the issuing admin recorded as creator. M2M token exchanges surface as discrete audit events (issued, denied, or failed), so you see not just what the agent did but when and how it authenticated.

Safety considerations​

  • Over-broad credentials are the main risk. An agent whose MCP contains forty connectors and a thousand tools is a large target. Prefer a narrow MCP sized to the actual job: if the job grows, grow its tool set rather than handing the agent a general-purpose one.
  • Agents can't consent. Every OAuth "are you sure?", every MFA challenge, every incremental scope consent: none of that is available to a running agent. The credential model pushes toward shared downstream credentials with rules and tool curation as the controls, which shifts responsibility: you decide what the agent can do, because the downstream sees one service account doing everything.
  • Tokens leak. Treat agent credentials like any other secret: use a secret manager, never put them in source. Prefer short-lived OAuth client-credentials tokens over long-lived bearer keys when the agent can handle the exchange.
  • One agent, one MCP, one purpose. If you reuse an agent across unrelated workflows, split it into two.
  • Review on a cadence. Agents tend to get created and forgotten. Periodically enumerate them, confirm each is still in use, and delete the rest, since an unused agent with a live credential is a dormant attack surface.
  • Watch the audit log. Agent traffic is separated from human traffic, so anomalies stand out cleanly.

Next steps​