# Bifrost Integration

Connect your [Bifrost MCP gateway](https://github.com/maximhq/bifrost) 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:

| Hook | Type | Description |
|  --- | --- | --- |
| **PreMCPHook** | Blocking | The tool call (server name, tool name, arguments) before it reaches the upstream MCP server — can deny on policy violation |
| **PostMCPHook** | Observation | Duration, 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.


```bash
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`:


```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

| Field | Type | Default | Description |
|  --- | --- | --- | --- |
| `endpoint` | `string` | *(required)* | Capsule Bifrost hooks endpoint, e.g. `https://agents.capsule.security/v1/bifrost/hooks` |
| `token` | `string` | *(required)* | JWT generated in Step 1, scoped to your tenant and environment |
| `timeout_ms` | `number` | `5000` | Per-request timeout in milliseconds for both pre and post hooks |
| `fail_open` | `boolean` | `true` | Allow the tool call when Capsule is unreachable. Set to `false` to fail closed |
| `enable_logging` | `boolean` | `false` | Log 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:


```bash
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:

```bash
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

- [Bifrost MCP Gateway](https://github.com/maximhq/bifrost)
- [Bifrost Plugin Configuration](https://github.com/maximhq/bifrost#plugins)