Enterprise MCP Gateway with Built-In Security: OAuth 2.0, RBAC, and Tool Access Control

TL;DR

MCP servers are powerful, but they can provide access to production systems if anyone on the team can connect and run tools without guardrails.

Imagine a new hire testing the app on their laptop and accidentally granting an MCP server access to the production database. Without governance, that is a realistic path to data leakage.

Bifrost addresses this with three layers:

1. Human-in-the-loop execution — Bifrost does not auto-execute tool calls. The LLM only suggests tools; your application reviews them and explicitly calls POST /v1/mcp/tool/execute.
2. Deny-by-default tool filtering — A virtual key with no mcp_configs gets zero MCP tools. Unlisted clients are implicitly blocked.
3. Governance (optional) — RBAC, SSO, audit logs, and MCP Tool Groups control who can configure the gateway and review administrative activity.

Bifrost covers virtual keys, budgets, rate limits, routing, and MCP tool filtering, RBAC, SSO, audit logs, and MCP Tool.

---

🔧 Using MCP server

First, let's open the app and set up the MCP server. To do this, I'll enter the following line in the terminal:

npx -y @maximhq/bifrost

After that, you will see the following interface (similar, depending on the version):

Go to the "MCP Library" tab and you will see a huge list of pre-configured MCP servers that you can use in your projects.

If you want to set up your own MCP server, go to MCP Gateway and click New MCP Server:

Here you can specify the connection URL, auth type, tool allowlists, and other settings including Code Mode, which can significantly reduce token usage when orchestrating many MCP servers.

💎 Star Bifrost ☆

---

⚙️ Human-in-the-loop tool

This is the most important security property for the scenario in the introduction.

When an LLM returns tool calls, Bifrost does not automatically execute them. Tool calls are suggestions only. Your application must explicitly approve and execute each one:

1. POST /v1/chat/completions   → LLM returns tool call suggestions (NOT executed)
2. Your app reviews tool calls → Apply security rules, get user approval if needed
3. POST /v1/mcp/tool/execute   → Execute approved tool calls explicitly
4. POST /v1/chat/completions   → Continue the conversation with tool results

Example execution call:

curl -X POST http://localhost:8080/v1/mcp/tool/execute \
  -H "Content-Type: application/json" \
  -d '{
    "id": "call_xyz789",
    "type": "function",
    "function": {
      "name": "database_query",
      "arguments": "{\"sql\": \"SELECT 1\"}"
    }
  }'

So even if a new hire's agent requests a dangerous database operation, nothing happens until your application deliberately executes it. Combined with deny-by-default virtual key filtering (below), this is Bifrost's real three-layer answer to accidental production access.

You can opt into autonomous execution for specific tools via Agent Mode, but that must be explicitly configured, it is not the default.

---

💻 MCP authentication

Authentication is declared on the MCP client itself as a top-level auth_type field, posted to /api/mcp/client. There is no nested auth object.

auth_type	Who authenticates	When to use
none	—	Public MCP servers, local STDIO tools
headers	Admin, once	Shared API keys, bearer tokens, custom headers
oauth	Admin, once	Shared third-party service the whole team uses
per_user_oauth	Each end-user, lazily	Per-user services like Notion, GitHub, Sentry
per_user_headers	Each end-user, lazily	Per-user API keys, signed tokens

OAuth (oauth and per_user_oauth) is only valid for HTTP and SSE connections. Bifrost implements the Authorization Code flow, there is no client-credentials / service-account mode.

1. No auth (development only)

{
  "name": "local-tools",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-filesystem"]
  },
  "auth_type": "none",
  "tools_to_execute": ["read_file", "list_directory"]
}

2. Static headers (shared API keys)

curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web_search",
    "connection_type": "http",
    "connection_string": "https://mcp.example.com/mcp",
    "auth_type": "headers",
    "headers": {
      "Authorization": "Bearer your-api-key",
      "X-Tenant-ID": "acme-corp"
    },
    "tools_to_execute": ["*"]
  }'

3. Server-level OAuth (admin authorizes once)

The admin authenticates once during setup. Every subsequent request to that MCP server uses the same stored token, regardless of which caller hit Bifrost.

curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "authenticated_service",
    "connection_type": "http",
    "connection_string": "https://api.example.com/mcp",
    "auth_type": "oauth",
    "oauth_config": {
      "client_id": "your-client-id",
      "client_secret": "your-client-secret",
      "authorize_url": "https://auth.example.com/oauth/authorize",
      "token_url": "https://auth.example.com/oauth/token",
      "scopes": ["mcp:read", "mcp:write"]
    },
    "tools_to_execute": ["*"]
  }'

The oauth_config object accepts client_id, client_secret, authorize_url, token_url, scopes, or registration_url / server_url for Dynamic Client Registration. After the admin completes the authorize step, finalize with POST /api/mcp/client/{id}/complete-oauth.

4. Per-user OAuth (each user authenticates themselves)

Use auth_type: "per_user_oauth" when each end-user must connect under their own account. Bifrost stores one OAuth token per (identity, mcp_client) and reuses it on later calls. Identity is required via virtual key, signed-in SSO user, or x-bf-mcp-session-id.

5. Per-user headers (legacy / custom per-user keys)

curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme_api",
    "connection_type": "http",
    "connection_string": "https://api.acme.example.com/mcp",
    "auth_type": "per_user_headers",
    "per_user_header_keys": ["X-API-Key", "X-Tenant-ID"],
    "tools_to_execute": ["*"]
  }'

Identity matters: With auth_type: "oauth" or auth_type: "headers", all callers share the same upstream credential. Bifrost does not attach a per-user identity to MCP requests. To know exactly who performed an action upstream, use per_user_oauth or per_user_headers.

---

💻 Runtime tool access control (Virtual Keys)

RBAC does not govern which MCP tools an agent can invoke at runtime. That is controlled by virtual keys and three stacked levels of tool filtering:

1. Client config — tools_to_execute on each MCP client (baseline)
2. Request headers — x-bf-mcp-include-clients and x-bf-mcp-include-tools per request
3. Virtual key config — mcp_configs array (takes precedence over request headers)

Deny-by-default

This is built-in behavior, not a config setting: a virtual key with no mcp_configs gets zero MCP tools, and clients not listed in mcp_configs are implicitly blocked.

Virtual key configuration

curl -X POST http://localhost:8080/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-dev-key",
    "mcp_configs": [
      {
        "mcp_client_name": "internal_api",
        "tools_to_execute": ["search", "get_article"]
      },
      {
        "mcp_client_name": "staging_database",
        "tools_to_execute": ["query"]
      }
    ]
  }'

tools_to_execute	Result
["*"]	All tools from this client
["a", "b"]	Only specified tools
[]	No tools from this client
Client not in mcp_configs	All tools blocked from that client

This is where you enforce patterns like "backend devs can hit staging APIs but not production databases" by giving different virtual keys different mcp_configs, not by RBAC permission strings.

Per-request narrowing

For one-off restrictions within a virtual key's allowlist:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer vk_new_dev" \
  -H "x-bf-mcp-include-tools: staging_database-query" \
  -d '...'

Note: when a virtual key has mcp_configs, it auto-generates x-bf-mcp-include-tools and overrides any manually sent header.

Bifrost does not parse SQL or block operations like DELETE / DROP at the query level. Restrict access by allowing only specific tool names (for example, a read-only query tool instead of an execute tool).

---

🔎 RBAC — administrative access

Bifrost provides Role-Based Access Control for the administrative surface who can edit MCP gateway configs, read logs, configure guardrails, manage virtual keys, and so on. RBAC is not runtime authorization for agents invoking MCP tools.

Permissions are Resource × Operation pairs, not permission strings like mcp:tool:invoke.

System roles

Role	Permissions	Description
Admin	42	Full access to all resources and operations
Developer	27	CRUD on technical resources, view access to logs and cluster
Viewer	14	Read-only access to all resources

You can also create custom roles (for example, an Auditor role with AuditLogs:View and Logs:View only).

Protected resources include

Logs, VirtualKeys, MCPGateway, MCPToolGroups, MCPLogs, GuardrailsConfig, AuditLogs, Cluster, and others.

Operations include

View, Create, Update, Delete, Download, Reveal, and inference operations.

Example: a custom Auditor role might grant AuditLogs:View and AuditLogs:Download, but not MCPGateway:Update. That controls who can configure the gateway in the dashboard, not which tools an agent executes at runtime.

Roles and permissions are managed via Governance → Roles & Permissions in the dashboard or the /api/roles endpoints:

curl -X GET http://localhost:8080/api/roles/{role_id}/permissions \
  -H "Authorization: Bearer <admin_token>"

---

🖥️ User Provisioning and role mapping

There is no role_sync config block. Role assignment comes from User Provisioning over OIDC, supported for Okta, Microsoft Entra and others.

When SSO is configured:

• Users sign in with corporate credentials via OAuth 2.0 / OIDC (Authorization Code + PKCE)
• Roles are mapped from IdP groups, app roles, or custom claims to Bifrost roles (Admin, Developer, Viewer, or custom roles)
• Role and team assignments are synchronized on each session
• Background reconciliation runs every 24 hours; OIDC session refresh checks run every 15 minutes
• Inactive or deprovisioned users are decommissioned locally (including via inbound SCIM 2.0)

Configuration lives under scim_config in config.json. See the User Provisioning docs for provider-specific setup guides.

---

📋 Audit logs

Audit logs in Bifrost record administrative activity who changed what, when, and which resource was affected. They do not use a log_level / capture / export_to block.

Real configuration shape:

{
  "audit_logs": {
    "disabled": false,
    "hmac_key": "env.AUDIT_HMAC_KEY",
    "retention_days": 365,
    "object_storage": {
      "type": "s3",
      "bucket": "acme-audit-archive",
      "prefix": "acme-prod",
      "compress": true,
      "region": "us-east-1",
      "access_key_id": "env.AUDIT_S3_KEY",
      "secret_access_key": "env.AUDIT_S3_SECRET"
    }
  }
}

Key features:

• Signed events — configure an HMAC key for verification
• Dashboard review — filter by search text, action, outcome, and date range
• Export — JSON, JSON Lines, or Syslog (requires AuditLogs:Download permission)
• Retention — retention_days controls database retention
• Object storage archival — optional mirror to S3/GCS for long-term compliance retention

View audit entries at Governance → Audit Logs in the dashboard.

---

✅ Implementation best practices

1. Rely on deny-by-default

Do not look for a "policy": "default_deny" setting. It does not exist. Instead:

• Create virtual keys with explicit mcp_configs for each team or environment
• Set client-level tools_to_execute to the minimum needed
• Leave production database tools off keys used for local development

2. Keep human-in-the-loop as the default

Only enable Agent Mode auto-execution for tools you have explicitly reviewed. The default flow — chat → review → /v1/mcp/tool/execute — is your strongest safety net.

3. Separate runtime access from admin access

• Runtime (what agents can do): virtual keys + mcp_configs + request headers
• Administration (who can change configs): RBAC + SSO

4. Use environment-scoped virtual keys

{
  "name": "production-readonly",
  "mcp_configs": [
    { "mcp_client_name": "production_database", "tools_to_execute": ["query"] }
  ]
}

{
  "name": "staging-full",
  "mcp_configs": [
    { "mcp_client_name": "staging_database", "tools_to_execute": ["*"] }
  ]
}

5. Configure audit logging early

Enable HMAC signing, set retention_days comfortably above your archival window, and optionally mirror to object storage for compliance.

6. Perform regular access reviews

Schedule quarterly reviews to answer:

• Which virtual keys grant access to production MCP clients?
• Who has Admin or Developer RBAC roles in Enterprise?
• Are there overprivileged virtual keys or dormant SSO accounts?

Use the dashboard and /api/roles endpoints, there is no bifrost audit CLI command. The @maximhq/bifrost-cli package is an interactive launcher for coding agents (Claude Code, Codex CLI, Gemini CLI, Opencode), not an audit tool.

---

🖋️ Conclusion

With Bifrost, you can configure your company's MCP server much more securely. This ready-made solution will save you not only money but also time, which can be spent on product development.

---

🔗 Resources:

• Bifrost GitHub: https://github.com/maximhq/bifrost
• Bifrost Docs: https://docs.getbifrost.ai
• Bifrost CLI: npx -y @maximhq/bifrost-cli

Thanks for reading this article! ❤️

I'd love to hear your thoughts on this mode in the comments!

Comments

[Anthony Max]

Do you use MCP servers in your work?