MCP Identity Broker

Keep MCP agents from acting as the wrong account.

MCP Identity Broker is a local stdio MCP server for teams that run agents across more than one account, brand, client, or repository. Before an agent can use a provider, it must acquire a named identity. That lease is exclusive, time-limited, and limited to the provider tools you allow.

agent principal -> identity lease -> isolated provider process -> provider account

The broker does not store credentials. Your secret manager or environment injects them only into the provider process for the identity being used.

When this helps

Use this when one agent host can reach more than one account and "whoever is currently logged in" is not an acceptable permission model. Typical examples:

• separate GitHub accounts for a product and a client;
• separate mailboxes for separate brands;
• an operations agent that may read one service but must not touch another.

If every task uses one account and one provider, you probably do not need this.

What it does

For each configured identity, the broker:

• permits only named principals to acquire it;
• grants one holder an exclusive lease with a time-to-live;
• starts the configured upstream stdio MCP provider with that identity's environment only;
• allows only the provider tools listed in that identity's configuration; and
• returns audit metadata without returning credentials.

What it does not do

• It cannot switch or take over a hosted connector's shared OAuth session.
• It is not a secret manager or a substitute for provider-side least privilege.
• It is not multi-user authentication. Run one broker per trusted principal, or put it behind an authenticated transport that derives the principal server-side.
• It does not make an untrusted local machine safe.

Quick start

1. Install and create local config

Requires Node.js 20 or later. Clone this repository, then run:

npm install
Copy-Item config.example.json identity-broker.json

identity-broker.json is intentionally ignored by Git. It contains no literal secrets, but it does describe your account aliases and allowed tools.

2. Provide a principal and provider credentials

Use your operating system, vault, or secret-injection tool to provide the variables referenced by your local config. For the GitHub example:

$env:IDENTITY_BROKER_PRINCIPAL = "brand-a-agent"
$env:BRAND_A_GITHUB_TOKEN = "<token from your secret manager>"
$env:BRAND_A_GITHUB_TOOLS = "get_file_contents,issue_read,create_issue"

Never commit a token. The broker rejects literal credential values in its JSON configuration.

3. Start the broker

node src/server.js --config "$PWD\identity-broker.json"

Configure that command as a local stdio MCP server in your agent host. The host receives four broker tools:

Tool	Use it to
identity_status	Check accessible identities, lease state, and allowed tools.
identity_acquire	Acquire an identity and receive a lease ID.
identity_invoke	Call one allowlisted provider tool with that lease.
identity_release	Release the lease when the work is complete.

The normal call sequence is:

status -> acquire -> invoke -> release

An expired or released lease cannot invoke a provider tool. A second holder cannot acquire an identity while it is leased.

Adopt it in an existing project

If a project already has an agent in progress, give it a small identity contract instead of relying on a remembered account or browser session.

1. Copy templates/project-identity.json to .mcp-identity.json in the project. Use an alias and principal that are specific to that project; never put a credential in this file.
2. Add templates/AGENTS.identity-broker.md to the project's agent instructions. Claude Code users can place the same instructions in CLAUDE.md.
3. Register this broker once in the agent host, with a launcher that fixes the principal and supplies only that project's provider credentials.

After that, an MCP-capable coding agent can read .mcp-identity.json, acquire the configured identity, use an allowlisted provider tool, and release the lease. The file tells the agent which identity to use; the broker remains the enforcement point.

This is intentionally not automatic just because an agent can see this GitHub repository. A host must explicitly install a local stdio MCP server before it can launch local code or access credentials.

Configure identities

The example config shows the shape:

{
  "identities": {
    "brand-a": {
      "allowed_principals": ["brand-a-agent"],
      "providers": {
        "github": {
          "command": "docker",
          "args": ["run", "-i", "--rm", "..."],
          "allowed_tools": ["get_file_contents", "issue_read"],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "${BRAND_A_GITHUB_TOKEN}"
          }
        }
      }
    }
  }
}

Each provider needs a command, arguments, an explicit tool allowlist, and environment-variable references. The broker resolves those references only when it starts the upstream provider process.

The included GitHub example uses the official GitHub MCP server. Docker is optional if you install the official binary and update command and args in your local config.

GitHub CLI account helper

scripts/start-github-identity-broker.mjs is an optional launcher for a GitHub CLI setup that already stores multiple accounts. It reads the selected identity and provider from your config, then makes that account's token available to the broker child process only. It does not run gh auth switch, so it does not change another agent's active GitHub CLI account.

node .\scripts\start-github-identity-broker.mjs `
  --config "$PWD\identity-broker.json" `
  --github-user brand-a-github `
  --principal brand-a-agent `
  --identity brand-a

Security notes

• Keep local config permission-restricted.
• Use short-lived, provider-scoped credentials where possible.
• Allow only the tools needed for the specific identity.
• Treat a broker restart as lease invalidation. Leases are in memory in v0.1.
• Read SECURITY.md before using production credentials.

Development

npm test

The test suite covers exclusive leases, expiry, cross-principal isolation, and rejection of literal credentials in configuration.

Assess a configuration

Run the included Identity Boundary Assessment to create a safe, repeatable pass/fail report for a broker configuration. It does not start a provider or read a credential.

npm run eval:identity-boundary -- .\identity-broker.json

Fixed-scope assessment

The broker stays free and open source. Teams that need help applying it can buy an Identity Boundary Assessment: one agent host, up to three account aliases, two providers, and ten permitted actions. The fixed price is $1,500 USD. The deliverable is a private map, boundary findings, fixes, and a rerun proof within five business days.

Buy the assessment

This is not an enterprise IAM deployment or a penetration test. Read the report template before buying so the acceptance criteria are explicit.

The optional Stripe launcher requires a dedicated MARKSIGNALS_STRIPE_API_KEY. It performs no action without --publish:

node .\scripts\create-stripe-assessment-link.mjs
node .\scripts\create-stripe-assessment-link.mjs --publish

The standard Stripe One-time payments restricted-key template supplies the write permissions this launcher needs. It does not need account-profile read permission.

License

MIT