{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Bifrost Integration","description":"Control the power of AI Agents in runtime.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"bifrost-integration","__idx":0},"children":["Bifrost Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Connect your ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://github.com/maximhq/bifrost"},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following hooks are configured:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Hook"},"children":["Hook"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PreMCPHook"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blocking"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The tool call (server name, tool name, arguments) before it reaches the upstream MCP server — can deny on policy violation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PostMCPHook"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Observation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duration, success/failure, and error detail after the upstream call resolves"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you begin, ensure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A running ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bifrost MCP gateway"]}," (Go 1.22 or later)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The same Go toolchain and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bifrost/core"]}," source version used to build your Bifrost binary"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," account with admin access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Network access from your Bifrost gateway to your Capsule agentsecurity endpoint (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://agents.capsule.security"]},")"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-generate-a-plugin-token","__idx":3},"children":["Step 1: Generate a Plugin Token"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log in to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," portal."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integrations"]}," and locate ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bifrost"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Install"]}," — Capsule generates a JWT scoped to your tenant and Bifrost environment. Treat it as a secret."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Copy the generated ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["endpoint"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["token"]},". You will reference them in the plugin configuration in the next steps."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-build-the-plugin","__idx":4},"children":["Step 2: Build the Plugin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go plugins are ABI-coupled to the Bifrost binary that loads them. The plugin ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," be compiled with the same Go toolchain version and against the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bifrost/core"]}," source as your Bifrost deployment."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"git clone https://github.com/capsulesecurity/capsule.git\ncd capsule/plugins/bifrost-plugin\nmake tidy   # resolve dependencies against your pinned bifrost/core version\nmake build  # outputs build/capsule.so\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your Bifrost deployment tracks a different ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bifrost/core"]}," tag than the one pinned in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["go.mod"]},", update the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["require"]}," line before running ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["make tidy"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-configure-the-plugin","__idx":5},"children":["Step 3: Configure the Plugin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reference the built plugin in your Bifrost ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["config.yaml"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"plugins:\n  - name: capsule\n    path: ./build/capsule.so\n    config:\n      endpoint: \"https://agents.capsule.security/v1/bifrost/hooks\"\n      token: \"${CAPSULE_BIFROST_TOKEN}\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}," field supports environment variable interpolation — keep the raw JWT out of version control."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-options","__idx":6},"children":["Configuration Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(required)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Capsule Bifrost hooks endpoint, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://agents.capsule.security/v1/bifrost/hooks"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(required)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT generated in Step 1, scoped to your tenant and environment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout_ms"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5000"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Per-request timeout in milliseconds for both pre and post hooks"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fail_open"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allow the tool call when Capsule is unreachable. Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to fail closed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enable_logging"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Log allow/deny decisions to stdout"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"token-storage","__idx":7},"children":["Token Storage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never commit the JWT to version control. Recommended approaches:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass the token as an environment variable (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPSULE_BIFROST_TOKEN"]},") and use interpolation in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["config.yaml"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Source it from your secret manager (1Password, AWS Secrets Manager, HashiCorp Vault) at gateway startup"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deliver it through the same channel that distributes the rest of your Bifrost deployment configuration"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-restart-bifrost","__idx":8},"children":["Step 4: Restart Bifrost"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Restart the gateway to load the plugin:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"bifrost --config config.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bifrost logs registered plugins on startup. Confirm the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capsule"]}," plugin appears in the output."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-verify-the-installation","__idx":9},"children":["Step 5: Verify the Installation"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trigger a tool call through the gateway."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log in to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," portal."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inventory > Agents"]}," and confirm a Bifrost agent appears."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click the agent and review the audit logs to verify pre-call and post-call events are captured."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"troubleshooting","__idx":10},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If events are not appearing:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify the endpoint is reachable"]}," from the gateway host:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -sS -o /dev/null -w \"%{http_code}\\n\" https://agents.capsule.security/v1/bifrost/hooks/events/pre\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify the JWT is valid"]}," — a 401 response from the endpoint means the token is missing, expired, or scoped to a different environment."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check for timeouts"]}," — if your network has high latency to the Capsule endpoint, increase ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout_ms"]}," or confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fail_open"]}," is set appropriately."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Confirm the plugin is loaded"]}," — Bifrost logs registered plugins on startup; the Capsule plugin registers as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capsule"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contact Capsule Security support"]}," if issues persist."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-considerations","__idx":11},"children":["Security Considerations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Capsule plugin runs in-process inside the Bifrost gateway and observes every outbound tool call. Before deploying:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Protect the JWT"]}," — anyone with the token can post events on behalf of your tenant. Rotate it through the portal if it is exposed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Choose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fail_open"]}," deliberately"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," (the default) prioritizes availability and lets tool calls through when Capsule is unreachable; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," prioritizes policy enforcement and blocks tool calls when Capsule cannot be reached."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ABI-pin the plugin"]}," — rebuild ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capsule.so"]}," whenever you upgrade Bifrost to avoid loader panics from Go plugin ABI mismatches."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use TLS-only endpoints"]},". The plugin sends a Bearer token on every request — never configure an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http://"]}," endpoint outside local development."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"support","__idx":12},"children":["Support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For help with this integration:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Email"]},": support@capsule.security"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Include"]},": Your organization ID, integration status, plugin version (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["git rev-parse HEAD"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bifrost-plugin"]}," directory), and any error messages"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"references","__idx":13},"children":["References"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://github.com/maximhq/bifrost"},"children":["Bifrost MCP Gateway"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://github.com/maximhq/bifrost#plugins"},"children":["Bifrost Plugin Configuration"]}]}]}]},"headings":[{"value":"Bifrost Integration","id":"bifrost-integration","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Generate a Plugin Token","id":"step-1-generate-a-plugin-token","depth":2},{"value":"Step 2: Build the Plugin","id":"step-2-build-the-plugin","depth":2},{"value":"Step 3: Configure the Plugin","id":"step-3-configure-the-plugin","depth":2},{"value":"Configuration Options","id":"configuration-options","depth":3},{"value":"Token Storage","id":"token-storage","depth":3},{"value":"Step 4: Restart Bifrost","id":"step-4-restart-bifrost","depth":2},{"value":"Step 5: Verify the Installation","id":"step-5-verify-the-installation","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":3},{"value":"Security Considerations","id":"security-considerations","depth":2},{"value":"Support","id":"support","depth":2},{"value":"References","id":"references","depth":2}],"frontmatter":{"seo":{"title":"Bifrost Integration"}},"lastModified":"2026-06-22T10:33:23.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/bifrost","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}