Skip to content
Guides
/
/
Bifrost
Last updated

Bifrost Integration

Connect your Bifrost MCP gateway to Capsule Security for real-time policy enforcement and audit of every outbound MCP tool call — before the upstream server executes it.

Overview

This integration uses a Go plugin that Bifrost loads at startup. Before each MCP tool call is forwarded to the upstream server, the plugin synchronously posts the request to your Capsule tenant and blocks on an allow/deny verdict. After the call settles, it fires fire-and-forget telemetry.

Bifrost is operator-deployed — you run the gateway in your own infrastructure, so there is no SaaS install. The only thing exchanged at install time is a signed JWT that scopes the plugin to your tenant and environment.

The following hooks are configured:

HookTypeDescription
PreMCPHookBlockingThe tool call (server name, tool name, arguments) before it reaches the upstream MCP server — can deny on policy violation
PostMCPHookObservationDuration, success/failure, and error detail after the upstream call resolves

Prerequisites

Before you begin, ensure you have:

  • A running Bifrost MCP gateway (Go 1.22 or later)
  • The same Go toolchain and bifrost/core source version used to build your Bifrost binary
  • A Capsule Security account with admin access
  • Network access from your Bifrost gateway to your Capsule agentsecurity endpoint (e.g. https://agents.capsule.security)

Step 1: Generate a Plugin Token

  1. Log in to the Capsule Security portal.

  2. Navigate to Integrations and locate Bifrost.

  3. Click Install — Capsule generates a JWT scoped to your tenant and Bifrost environment. Treat it as a secret.

  4. Copy the generated endpoint and token. You will reference them in the plugin configuration in the next steps.

Step 2: Build the Plugin

Go plugins are ABI-coupled to the Bifrost binary that loads them. The plugin must be compiled with the same Go toolchain version and against the same bifrost/core source as your Bifrost deployment.

git clone https://github.com/capsulesecurity/capsule.git
cd capsule/plugins/bifrost-plugin
make tidy   # resolve dependencies against your pinned bifrost/core version
make build  # outputs build/capsule.so

If your Bifrost deployment tracks a different bifrost/core tag than the one pinned in go.mod, update the require line before running make tidy.

Step 3: Configure the Plugin

Reference the built plugin in your Bifrost config.yaml:

plugins:
  - name: capsule
    path: ./build/capsule.so
    config:
      endpoint: "https://agents.capsule.security/v1/bifrost/hooks"
      token: "${CAPSULE_BIFROST_TOKEN}"

The token field supports environment variable interpolation — keep the raw JWT out of version control.

Configuration Options

FieldTypeDefaultDescription
endpointstring(required)Capsule Bifrost hooks endpoint, e.g. https://agents.capsule.security/v1/bifrost/hooks
tokenstring(required)JWT generated in Step 1, scoped to your tenant and environment
timeout_msnumber5000Per-request timeout in milliseconds for both pre and post hooks
fail_openbooleantrueAllow the tool call when Capsule is unreachable. Set to false to fail closed
enable_loggingbooleanfalseLog allow/deny decisions to stdout

Token Storage

Never commit the JWT to version control. Recommended approaches:

  • Pass the token as an environment variable (CAPSULE_BIFROST_TOKEN) and use interpolation in config.yaml
  • Source it from your secret manager (1Password, AWS Secrets Manager, HashiCorp Vault) at gateway startup
  • Deliver it through the same channel that distributes the rest of your Bifrost deployment configuration

Step 4: Restart Bifrost

Restart the gateway to load the plugin:

bifrost --config config.yaml

Bifrost logs registered plugins on startup. Confirm the capsule plugin appears in the output.

Step 5: Verify the Installation

  1. Trigger a tool call through the gateway.

  2. Log in to the Capsule Security portal.

  3. Navigate to Inventory > Agents and confirm a Bifrost agent appears.

  4. Click the agent and review the audit logs to verify pre-call and post-call events are captured.

Troubleshooting

If events are not appearing:

  1. Verify the endpoint is reachable from the gateway host:

    curl -sS -o /dev/null -w "%{http_code}\n" https://agents.capsule.security/v1/bifrost/hooks/events/pre

  2. Verify the JWT is valid — a 401 response from the endpoint means the token is missing, expired, or scoped to a different environment.

  3. Check for timeouts — if your network has high latency to the Capsule endpoint, increase timeout_ms or confirm fail_open is set appropriately.

  4. Confirm the plugin is loaded — Bifrost logs registered plugins on startup; the Capsule plugin registers as capsule.

  5. Contact Capsule Security support if issues persist.

Security Considerations

The Capsule plugin runs in-process inside the Bifrost gateway and observes every outbound tool call. Before deploying:

  1. Protect the JWT — anyone with the token can post events on behalf of your tenant. Rotate it through the portal if it is exposed.
  2. Choose fail_open deliberately — true (the default) prioritizes availability and lets tool calls through when Capsule is unreachable; false prioritizes policy enforcement and blocks tool calls when Capsule cannot be reached.
  3. ABI-pin the plugin — rebuild capsule.so whenever you upgrade Bifrost to avoid loader panics from Go plugin ABI mismatches.
  4. Use TLS-only endpoints. The plugin sends a Bearer token on every request — never configure an http:// endpoint outside local development.

Support

For help with this integration:

  • Email: support@capsule.security
  • Include: Your organization ID, integration status, plugin version (git rev-parse HEAD in the bifrost-plugin directory), and any error messages

References

Previous page
Next page