MCP Credentials Broker

A secure credential management layer for Model Context Protocol (MCP) servers. Authenticate providers via browser — no hardcoded API keys, no tokens pasted into chat.

Why Use This?

If you're building MCP servers that need to access external APIs (GitHub, Google, Azure, etc.), you've probably hardcoded API keys in environment variables or pasted tokens into chat. This broker solves that by:

Authenticating providers via browser OAuth2 — you just log in, the broker handles the rest
Issuing short-lived references instead of exposing raw tokens to the agent
Centralizing credential management across all MCP servers in a single session

How It Works

You say: "List my GitHub repos"

Agent:
  1. Checks if github-token is already stored
  2. If not → triggers browser OAuth flow → you log in → token stored
  3. Gets a short-lived reference to the token
  4. Resolves the reference to the actual value (never shown to you)
  5. Passes the token to your GitHub MCP tool

The agent handles all of this automatically via the included rules file — you never paste a token.

Installation

npm install @ars-system/mcp-credentials-broker

Or clone and build from source:

git clone https://github.com/ars-system/mcp-credentials-broker.git
cd mcp-credentials-broker
npm install
npm run build

Configuration

Step 1 — Get provider credentials (one-time)

The broker needs a client_id and client_secret for each provider you want to use. These are set once as environment variables — the agent never sees or asks for them.

GitHub

Go to github.com/settings/developers
Click OAuth Apps → New OAuth App
Fill in:
- Application name: MCP Credentials Broker (or anything)
- Homepage URL: http://localhost
- Authorization callback URL: http://localhost:9876/oauth/callback
Click Register application
Copy the Client ID
Click Generate a new client secret and copy it

GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

Google

Go to console.cloud.google.com/apis/credentials
Click Create Credentials → OAuth client ID
Application type: Web application
Add to Authorized redirect URIs: http://localhost:9876/oauth/callback
Copy the Client ID and Client Secret

GCP_CLIENT_ID=your-client-id
GCP_CLIENT_SECRET=your-client-secret

Azure

Go to portal.azure.com → Azure Active Directory → App registrations
Click New registration
Name it anything, select Accounts in any organizational directory and personal Microsoft accounts
Set redirect URI to: http://localhost:9876/oauth/callback (type: Web)
After creation, go to Certificates & secrets → New client secret
Copy the Application (client) ID and the secret value

AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

Okta

Go to your Okta Admin Console → Applications → Create App Integration
Select OIDC - OpenID Connect → Web Application
Add http://localhost:9876/oauth/callback to Sign-in redirect URIs
Copy the Client ID and Client Secret
Also set your Okta domain:

OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret
OKTA_DOMAIN=your-org.okta.com

Step 2 — Configure your MCP client

Add the broker alongside your other MCP servers. Pass the provider env vars in the env block:

{
  "mcpServers": {
    "credentials-broker": {
      "command": "node",
      "args": ["/path/to/mcp-credentials-broker/dist/index.js"],
      "env": {
        "GITHUB_CLIENT_ID": "your-github-client-id",
        "GITHUB_CLIENT_SECRET": "your-github-client-secret",
        "GCP_CLIENT_ID": "your-gcp-client-id",
        "GCP_CLIENT_SECRET": "your-gcp-client-secret"
      }
    },
    "your-github-mcp": {
      "command": "node",
      "args": ["/path/to/your-github-mcp/dist/index.js"]
    }
  }
}

Only configure the providers you actually use. You don't need all of them.

Step 3 — Add the agent rules (for Amazon Q / Claude / Cursor)

Add the following rules to your agent configuration (e.g., in .amazonq/rules/credentials-broker.md or your agent's custom rules file). These rules ensure the agent always uses the broker automatically and never asks you for tokens.

Copy the entire section below:

# Credentials Broker — Agent Rules

You have access to a `credentials-broker` MCP server. Follow these rules strictly.

## Rule 1 — Never ask the user for API tokens, passwords, or secrets

If a task requires a token (GitHub, Google, Azure, AWS, etc.), use the broker to obtain it.
Never ask the user to paste a token into the chat.

## Rule 2 — Check if a token is already stored before authenticating

Before triggering an OAuth flow, always check if the token already exists:

get_secret(name: "-token", purpose: "check")


If it succeeds, use that reference. Only call `start_oauth_flow` if the secret is missing or expired.

## Rule 3 — OAuth flow requires no credentials from the user

Call `start_oauth_flow` with only `provider`, `scopes`, and `secret_name`.
The broker reads `client_id` and `client_secret` from its own environment — you must NOT ask the user for these.

start_oauth_flow( provider: "github", scopes: ["repo", "read:user"], secret_name: "github-token" )


Tell the user: "A browser window will open for you to log in. Come back here once done."

## Rule 4 — Standard token retrieval pattern

Every time you need a token to pass to another MCP tool, follow this exact sequence:

**Step 1** — Get a short-lived reference:

get_secret(name: "github-token", purpose: "<what you're doing>", ttl_seconds: 3600) → returns { reference: { id: "ref-uuid" } }


**Step 2** — Resolve the reference to the actual value:

resolve_secret(reference_id: "ref-uuid") → returns { value: "gho_actualtoken..." }


**Step 3** — Pass `value` to the target MCP tool's token/auth parameter.

## Rule 5 — Never log or display raw token values

After calling `resolve_secret`, use the value directly in the next tool call.
Do not print it, summarize it, or include it in any response to the user.

## Rule 6 — Naming convention for stored secrets

Use consistent names so tokens can be reused across tool calls in the same session:

| Provider | secret_name        |
|----------|--------------------|
| GitHub   | `github-token`     |
| Google   | `google-token`     |
| Azure    | `azure-token`      |
| Okta     | `okta-token`       |
| Custom   | `<service>-token`  |

## Rule 7 — Provider configuration errors

If `start_oauth_flow` fails with "not configured", tell the user:
> "The broker needs `<PROVIDER>_CLIENT_ID` and `<PROVIDER>_CLIENT_SECRET` set as environment variables where the broker is running. These are set once by you — I won't ask for them again."

## Summary flow

Need a token? └─ get_secret("github-token") → exists? → resolve_secret → use it → missing? → start_oauth_flow → get_secret → resolve_secret → use it

Available Tools

`start_oauth_flow`

Opens the browser for you to log in. Stores the resulting token under secret_name. No credentials needed from you — the broker reads client_id and client_secret from its environment.

Parameter	Required	Description
`provider`	yes	`github`, `google`, `azure`, `okta`, `oauth2`
`scopes`	yes	List of OAuth2 scopes to request
`secret_name`	yes	Name to store the token under
`authorization_endpoint`	no	Custom auth URL (only for `okta` / `oauth2`)
`token_endpoint`	no	Custom token URL (only for `okta` / `oauth2`)

{
  "provider": "github",
  "scopes": ["repo", "read:user"],
  "secret_name": "github-token"
}

`get_secret`

Issues a short-lived reference to a stored secret. Returns a reference ID, not the raw value.

Parameter	Required	Description
`name`	yes	Name of the stored secret
`purpose`	yes	Why you're requesting it (for audit)
`ttl_seconds`	no	How long the reference is valid (default: 3600)

{
  "name": "github-token",
  "purpose": "listing repositories",
  "ttl_seconds": 3600
}

Response:

{
  "reference": {
    "id": "ref-uuid",
    "name": "github-token",
    "expiresIn": 3600
  }
}

`resolve_secret`

Resolves a reference ID to the actual token value. Used by the agent immediately before passing the token to another MCP tool.

Parameter	Required	Description
`reference_id`	yes	The `id` returned by `get_secret`

{ "reference_id": "ref-uuid" }

Response:

{ "value": "gho_actualtoken..." }

`store_secret`

Manually store a secret (e.g. a static API key). Use get_secret + resolve_secret to retrieve it later.

Parameter	Required	Description
`name`	yes	Identifier for the secret
`value`	yes	The secret value
`tags`	no	Key-value tags for organization

`mint_token`

Generates a short-lived JWT-based token scoped to a provider. Useful when you want a broker-issued token rather than a raw OAuth token.

Parameter	Required	Description
`provider`	yes	`github`, `aws`, `gcp`, `azure`, `oauth2`, `okta`
`scopes`	yes	List of scopes/permissions
`resource`	no	Resource identifier
`ttl_seconds`	no	Token lifetime (default: provider default)

`revoke_token`

Immediately invalidates a minted token.

Parameter	Required	Description
`token_id`	yes	ID of the token to revoke

`get_broker_stats`

Returns counts of active tokens, active references, and stored secrets.

End-to-End Example

You:   "Create a GitHub issue in my repo"

Agent: 1. get_secret("github-token")           → not found
       2. start_oauth_flow(                     → browser opens
            provider: "github",
            scopes: ["repo"],
            secret_name: "github-token"
          )                                     → you log in → token stored
       3. get_secret("github-token",            → { id: "ref-abc" }
            purpose: "create issue")
       4. resolve_secret("ref-abc")             → { value: "gho_..." } ← never shown to you
       5. github-mcp/create_issue(              → issue created ✓
            token: "gho_...",
            title: "..."
          )

Provider TTL Limits

Provider	Default TTL	Max TTL
GitHub	1 hour	8 hours
AWS	1 hour	12 hours
GCP	1 hour	12 hours
Azure	1 hour	12 hours
Okta	1 hour	12 hours
OAuth2 (generic)	1 hour	24 hours

Architecture

┌──────────────────────────────────────────────────────┐
│                MCP Credentials Broker                │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │           OAuth Web Flow                    │    │
│  │  - Spins up local HTTP server on :9876      │    │
│  │  - Opens browser to provider auth URL       │    │
│  │  - Receives callback with auth code         │    │
│  │  - Exchanges code for access token          │    │
│  └─────────────────────────────────────────────┘    │
│                                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │           Credentials Manager               │    │
│  │  - In-memory secret storage                 │    │
│  │  - Short-lived reference issuance           │    │
│  │  - Token lifecycle & auto-expiry            │    │
│  │  - Provider config from env vars            │    │
│  └─────────────────────────────────────────────┘    │
│                                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │           MCP Server Interface               │    │
│  │  - Tool definitions & request handling      │    │
│  └─────────────────────────────────────────────┘    │
│                                                      │
└──────────────────────────────────────────────────────┘

Security Notes

Tokens are stored in memory only — they are lost when the broker process restarts
Raw token values are never returned by get_secret — only reference IDs
The agent rule file instructs the agent to never display resolved token values
Set JWT_SECRET env var in production to sign broker-issued tokens securely
The OAuth callback server only runs during an active start_oauth_flow call, then shuts down

Development

npm run watch   # TypeScript watch mode
npm run build   # Build
npm run dev     # Build + run
npm run lint    # Lint

Contributing

Contributions welcome! Please follow existing TypeScript patterns and maintain proper type definitions.

License

MIT — see LICENSE file for details

Resources

Built by @ars-system • Report Issues

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
.husky		.husky
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc.json		.prettierrc.json
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MCP Credentials Broker

Why Use This?

How It Works

Installation

Configuration

Step 1 — Get provider credentials (one-time)

GitHub

Google

Azure

Okta

Step 2 — Configure your MCP client

Step 3 — Add the agent rules (for Amazon Q / Claude / Cursor)

Available Tools

`start_oauth_flow`

`get_secret`

`resolve_secret`

`store_secret`

`mint_token`

`revoke_token`

`get_broker_stats`

End-to-End Example

Provider TTL Limits

Architecture

Security Notes

Development

Contributing

License

Resources

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

MCP Credentials Broker

Why Use This?

How It Works

Installation

Configuration

Step 1 — Get provider credentials (one-time)

GitHub

Google

Azure

Okta

Step 2 — Configure your MCP client

Step 3 — Add the agent rules (for Amazon Q / Claude / Cursor)

Available Tools

start_oauth_flow

get_secret

resolve_secret

store_secret

mint_token

revoke_token

get_broker_stats

End-to-End Example

Provider TTL Limits

Architecture

Security Notes

Development

Contributing

License

Resources

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`start_oauth_flow`

`get_secret`

`resolve_secret`

`store_secret`

`mint_token`

`revoke_token`

`get_broker_stats`

Packages