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

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

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

Google

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

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

Azure

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

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

Okta

1. Go to your Okta Admin Console → Applications → Create App Integration
2. Select OIDC - OpenID Connect → Web Application
3. Add http://localhost:9876/oauth/callback to Sign-in redirect URIs
4. Copy the Client ID and Client Secret
5. 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

• Model Context Protocol Documentation
• MCP SDK for TypeScript

Built by @ars-system • Report Issues