bifrost-plugin MCP server
Commit Nov 12, 2026Enables Claude Code and Claude Desktop to connect to Bifrost MCP gateways with lifecycle hooks, skill discovery, and agent-driven memory.
Also known as neXenio/bifrost-plugin
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- MIT
What is bifrost-plugin MCP?
bifrost-plugin enables Claude Code and Claude Desktop to connect to Bifrost MCP gateways with lifecycle hooks, skill discovery, and agent-driven memory.
Summary generated from the project's README
About bifrost-plugin MCP server
Connecting Claude Code and Claude Desktop to Bifrost MCP gateways is what this plugin enables through advanced lifecycle hooks and agent-driven memory. It is designed for developers using Claude's CLI or Desktop environments who need to integrate remote gateways with automated skill discovery and persistent context. The plugin manages the connection using a gateway URL and a virtual key, which users can obtain via a company sign-in process.
Functionality varies depending on the interface used. In the Claude Code CLI and the Desktop Cowork tab, the plugin provides full support for hooks, subagents, and slash commands. On the web chat or Desktop Chat tab, it operates in a degraded mode that still allows access to MCP tools and skills but lacks the automated memory injection and lifecycle hooks. The system uses background workers to refresh local caches hourly and can automatically inject recalled memory and skill hints at the start of a session to improve agent performance.
What you can do with it
- 1Automated session context injectionAn AI agent can automatically receive recalled memory and skill library information at the start of a new session.
- 2Durable decision loggingDevelopers can use the plugin to save important decisions made during a session into a markdown file for future reference.
- 3Capability usage trackingThe plugin monitors which tool classes are being used and whether those calls are successful without sending sensitive arguments.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
BIFROST_LEGACY_HOSTSBIFROST_SKILLS_SERVERBIFROST_URLBIFROST_VK
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenexenio/bifrost-plugin is public and reachablegithub.com/nexenio/bifrost-plugin ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/nexenio/bifrost-plugin ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubbifrost-plugin
Claude Code plugin for any Bifrost MCP gateway: plugin registration with lifecycle hooks, skill discovery, agent-driven memory, and MCP.
Primary Target: Claude Code Plugin Registration (includes hooks, skills, and memory). Other surfaces need a compatible connector and separate authentication verification.
The skill-discovery and memory features need a gateway that exposes a skill server and/or a memory server. Without them, the plugin still wires up the gateway and degrades gracefully — those features simply no-op.
What it does
| Pillar | Behavior |
|---|---|
| 1 — Plugin Lifecycle Hooks | Auto-injects recalled memory context at session start, enforces skill-discovery hints before non-trivial tasks, spools memory candidates, and tracks capability usage |
| 2 — Skill discovery | Non-trivial prompts get a hint to call the gateway's skill-search tool (<prefix><skills-server>-skill_search, see Tool names below) before starting |
| 3 — One-command onboarding | /plugin install bifrost-plugin or node scripts/install.js --key vk_… (or /bifrost-setup) |
| 4 — Agent-driven memory | Recalls context via gateway memory tools before non-trivial tasks and saves durable decisions after work |
The hooks, concretely
Six hook events are registered in hooks/hooks.json, run by
five scripts — PostToolUse and PostToolUseFailure share one. All of them fail
silently and always exit 0, so a broken gateway can never block a session.
| Event | Script | What it does |
|---|---|---|
SessionStart |
session-start.cjs |
Emits the gateway primer, skill library, MCP tool roster and recalled memory, all from a local cache (no blocking network). Spawns the detached refresh worker afterwards. |
UserPromptSubmit |
prompt-submit.cjs |
On task prompts, attempts bounded live skill/memory recall; falls back to a tapered discovery hint. |
PreToolUse |
route-hint.cjs |
Suggests an advertised gateway server for matching direct service calls, once per server per session. |
Stop (async) |
session-reflect.cjs |
Every few turns, asks whether anything was learned worth appending to the project's .bifrost/candidates.md. Never writes memory itself. |
PostToolUse / PostToolUseFailure (async) |
usage.cjs |
Counts, per session, which capability classes were used and whether calls succeeded. Counts only — never queries, arguments or results, and nothing leaves the machine. SessionStart reads it back to decide how hard to push. |
Cached context is emitted for up to 14 days and labelled with its age once past 24 hours, rather than withheld — the session that has been away longest is the one that needs the primer most. A background refresh runs at most hourly.
Automatic prompt recall can send up to 600 normalized prompt characters to enabled
skill and memory tools. Likely-secret checks are heuristics, not complete protection.
Set BIFROST_PROMPT_RECALL=0 locally to disable this automatically sent query; server
policy cannot override that opt-out. See prompt privacy.
See guidance/bifrost-guide.md for the full engineer guide.
Registration and connection modes
Support assessment: 2026-11-11, against the current platform documentation. Host component support does not prove that this plugin's authentication works there.
| Surface | This plugin's installation/connection status |
|---|---|
| Claude Code CLI, IDE, Desktop Code | Primary target. Install through /plugin, configure gateway_url and virtual_key, then verify /mcp and hook output. |
| Desktop Cowork | Host supports hooks and skills, but skips MCP entries referencing an option without a default. This plugin's virtual_key has no default; its bundled MCP connection is not established by installing it. Separate compatible connector/configuration and an actual Cowork test are required. |
| Desktop Chat / claude.ai chat | Host loads skills, treats commands as skills, and ignores hooks. It ignores MCP URLs containing ${user_config.*}, including this plugin's URL. Use an operator-provided fixed-URL connector with supported authentication; this repository does not prove that connection. |
See Anthropic's platform support table. Do not add a shared credential default or remove working Code configuration to make another surface accept the manifest. Manifest validation does not test a connection.
Install in Claude Code
Run /plugin marketplace add neXenio/bifrost-plugin, then /plugin install bifrost-plugin. Supply the gateway URL and personal key through plugin configuration;
change them later with /plugin configure. No separate MCP registration or shell
exports are needed for this path. Ask your gateway operator for key provisioning.
After updating the installed copy, run /reload-plugins where supported, or start a
new session. A changed MCP configuration reconnects on reload; an unchanged one keeps
its connection. Start a new session to verify SessionStart context. Repository commits
do not update private mirrors, installed copies, or existing session context.
Reload behavior.
Virtual key or sign-in
The virtual key (vk_..., self-served from
https://bifrost.culture4.life/) is the auth
path for the Claude Code plugin configuration. Paste it into virtual_key,
then verify the connection. Chat and Cowork have the limitations above.
With auto_login on and virtual_key blank, the first interactive session
opens the company sign-in page once and caches the key it gets back in
~/.cache/bifrost-plugin/vk. The plugin no longer ships an oauth block in
.mcp.json (removed in 1.9.0): Claude Code never substituted
${user_config.oauth_client_id} inside it, so Keycloak always received the
literal placeholder, and it offered a second, broken sign-in path next to the
working one. A wrong key returns a 401 with no WWW-Authenticate header;
clear the virtual_key field rather than leaving a bad one in it.
Legacy fallback: Desktop local proxy
Prefer the plugin install path above. Use this only where you cannot install
the plugin at all (~/Library/Application Support/Claude/claude_desktop_config.json
on macOS):
{
"mcpServers": {
"bifrost": {
"command": "npx",
"args": [
"mcp-remote", "https://bifrost.culture4.life/mcp",
"--transport", "http-only",
"--header", "x-bf-vk:${BIFROST_VK}"
],
"env": { "BIFROST_VK": "vk_<your-key>" }
}
}
}
No spaces around : in the --header arg (argument-parsing quirk on some
platforms). This file then contains your key, so treat it as a secret and
keep its permissions tight.
Configuration
The gateway URL and key come from the install-time plugin config
(gateway_url / virtual_key), and the hooks read those same values, so a
normal install needs nothing here. The env vars below are overrides, plus the
knobs that have no plugin-config equivalent (see
Persisting env vars).
Credentials resolve in this order: the BIFROST_URL + BIFROST_VK pair, then
the plugin config, then a scan of ~/.claude.json. Each source is
all-or-nothing, so a URL is never paired with a key from somewhere else.
| Var | Purpose | Default |
|---|---|---|
BIFROST_URL |
Overrides the gateway /mcp endpoint the hooks call. Only takes effect together with BIFROST_VK |
(unset: plugin config is used) |
BIFROST_VK |
Overrides the virtual key the hooks send as x-bf-vk. Only takes effect together with BIFROST_URL |
(unset: plugin config is used) |
BIFROST_SKILLS_SERVER |
Skill MCP server name — fallback for hook hints when auto-discovery cache is cold | skills |
Hooks auto-discover the real skill-server name from your gateway's tool list
(e.g. skills-skill_search → server skills). Check /mcp for the
prefix on *-skill_search / *-get_skill and set BIFROST_SKILLS_SERVER to
match if your gateway does not use the default skills.
| Var | Purpose | Default |
|---|---|---|
BIFROST_KB_WING |
Knowledgebase wing/scope narrowing the memory server's memory_search, sent as filters={"wing": …} |
(unset — KB recall skipped) |
BIFROST_KB_QUERY |
Query string used for the KB recall (falls back to the per-project memory query) | project-derived query |
BIFROST_KB_INJECT |
Set to 0 to disable the KB recall header at session start |
(enabled) |
BIFROST_MEMORY_INJECT |
Set to 0 to disable the memory recall header at session start |
(enabled) |
BIFROST_MEMORY_PRIME |
Set to 1 to also inject recalled facts (and KB facts) at session start. Off by default: the header then only carries the recall/store guidance and no memory_search runs at session start. Signed plugin-config field memoryPrime, lockable |
(off) |
BIFROST_SKILLS_INJECT |
Set to 0 to disable the skill-library primer at session start |
(enabled) |
BIFROST_REFRESH |
Set to 0 to disable the background cache refresh entirely (no session-start-initiated network traffic) |
(enabled) |
BIFROST_REFRESH_INTERVAL_MS |
Minimum interval between background gateway refreshes | 3600000 (1 hour) |
BIFROST_ALLOW_HTTP |
Set to 1 to let hooks contact a plain-HTTP gateway on a non-loopback host (legacy private-network deployments — the key crosses the wire unencrypted) |
(off — HTTPS or loopback only) |
Pre-approving the gateway's tools
By default Claude Code asks for permission the first time it calls each gateway
tool. A gateway exposes a lot of them, so that is a lot of prompts. To approve
the whole server once, add this to ~/.claude/settings.json (all your projects)
or to .claude/settings.json in one repo:
{
"permissions": {
"allow": [
"mcp__plugin_bifrost-plugin_bifrost",
"mcp__bifrost"
]
}
}
A bare mcp__<server> rule covers every tool on that server; mcp__<server>__<tool>
narrows it to one. Both names are listed above because the server is called
bifrost when its .mcp.json is picked up as a project MCP server and
plugin_bifrost-plugin_bifrost when it arrives through the plugin — run /mcp
to see which one you have. Extra rules for a server you do not have are inert.
Two caveats worth knowing before you rely on this:
- The plugin cannot ship this for you. A plugin manifest may only carry
agentandsubagentStatusLinesettings; apermissionsblock inplugin.jsonpassesclaude plugin validateand is then silently dropped at load time, so it looks applied and is not. Granting tool permission stays a decision on your side of the boundary, which is the right default — it just means this snippet is a manual step. - This is Claude Code only. Claude Desktop and claude.ai gate tools through
their own approval UI and do not read
settings.json. On those surfaces, approve the server when prompted.
For a fleet, the same block goes in the managed settings file your MDM deploys, which also stops individual users from removing it.
Running your own gateway
The plugin works against any Bifrost gateway — point BIFROST_URL at it. The only
deployment-specific behaviour is the endpoint-migration notice, which tells users on a
retired hostname where to move. It ships configured for the neXenio gateway and is
retargetable:
| Var | Purpose | Default |
|---|---|---|
BIFROST_LEGACY_HOSTS |
Comma-separated hostnames being retired. Matched exactly — a lookalike domain ending in one of these does not trigger it. | (unset — notice disabled) |
BIFROST_CANONICAL_URL |
Gateway URL the notice tells users to move to | https://bifrost.culture4.life/mcp |
The retired hostnames are not compiled in: they are per-machine tunnel endpoints,
and a plugin anyone can install should not ship a roster of one organisation's
infrastructure. Enabling the notice therefore takes one line of operator config — put
it where your team already sets env, e.g. ~/.claude/settings.json:
{ "env": { "BIFROST_LEGACY_HOSTS": "old-tunnel-a.example,old-tunnel-b.example" } }
Anyone still pointing at one of those hosts is then told, once per session, to move to
BIFROST_CANONICAL_URL. Without it the notice never fires and users on a retired
endpoint get no signal — which is the trade: nothing published, nothing automatic.
| BIFROST_KEYAPP_URL | SSO keyapp URL — powers the explicit /bifrost-setup browser provisioning flow and signed plugin-config delivery | keyapp_url option, else the gateway's origin |
| BIFROST_PLUGIN_CONFIG | Set to 0 to disable signed plugin-config delivery entirely (kill switch) | (enabled whenever a key is configured) |
| BIFROST_PROMPT_SKILLS | 0 turns off the per-prompt skill search (keyapp prompt-submit.skillSearch) | 1 |
| BIFROST_PROMPT_MEMORY | 0 turns off the per-prompt memory recall (keyapp prompt-submit.memoryRecall) | 1 |
| BIFROST_PROMPT_MEMORY_MIN | Minimum similarity for a recalled fact (keyapp prompt-submit.memoryMinSimilarity) | 0.55 |
| BIFROST_PROMPT_BUDGET_MS | Deadline for both per-prompt searches together (keyapp prompt-submit.budgetMs) | 1500 |
| BIFROST_ROUTE_HINT | 0 turns off the hint to use a gateway server instead of a direct API call (keyapp route-hint.enabled) | 1 |
| BIFROST_REFLECT_MEMORY_STORE | 1 lets the end-of-session check-in store verified facts with memory_store (keyapp session-reflect.memoryStore) | 0 |
| BIFROST_PLUGIN_CONFIG_TTL_MS | How long a fetched plugin-config stays fresh before the manifest is re-checked | 900000 (15 min) |
Signed plugin-config
Whenever a key is configured (env, plugin option or auto-login), the plugin fetches an
Ed25519-signed, content-addressed config bundle from keyapp
(hooks/lib/plugin-config.cjs). The bundle carries the administrator's hook
config plus a tri-state (always_on / available / off) policy for skills and
MCP tools, already merged with your own non-locked opt-ins on the server.
- Session start reads it from cache only — zero network, so a slow or dead gateway never delays or breaks a session. A detached worker refreshes it.
- It fails closed: a bad signature, a bundle whose
sha256does not match the signed manifest, or a gateway demanding a newer plugin means nothing from the server is applied — the last verified config (or none) stays in effect. - The signing key is pinned on first use. Rotations are only honoured when
signingKeyIdchanges; a silent key swap is refused and reported. - Fields an administrator has locked override the corresponding environment variable above. Unlocked fields still yield to your local setting.
Fact priming is opt-in (BIFROST_MEMORY_PRIME=1); the sizing below only applies when it
is on. Injected memory/KB sizing is adaptive, not a flat fact count — hooks/refresh.cjs
fetches a wider candidate pool from memory_search, then keeps the most similar
results within a character budget (higher-similarity facts get a larger snippet):
| Var | Purpose | Default |
|---|---|---|
BIFROST_MEMORY_MAX_FACTS |
Cap on facts injected per section (memory, KB) | 6 |
BIFROST_MEMORY_SNIPPET_LEN |
Base per-fact snippet length in characters | 180 |
BIFROST_INJECT_BUDGET |
Total character budget per section (~4 chars/token) | 2000 (~500 tokens) |
BIFROST_MEMORY_MIN_SIM |
Drop memory_search results below this score. Applies to luca-memory's similarity field (true cosine); needs a luca-memory that returns it, since older servers return only the RRF relevance and then nothing is injected. 0.55 comes from a replay of 770 real hook calls (judged precision about 0.82 at 0.55 vs 0.73 at 0.45) |
0.55 |
BIFROST_MEMORY_FAST |
Set to 1 to pass fast:true to memory_search (server-side fast path) |
0 (off — opt-in until the gateway ships the param) |
If memory_search returns similarity/score metadata, results are ranked and
budget-filled. Rows with no numeric score (an unrecognised response shape, plain
strings, the regex fallback) are dropped while any floor is active; they are kept
only when both BIFROST_MEMORY_MIN_SIM=0 and BIFROST_MEMORY_RELATIVE_FLOOR=0.
There is no separate KB MCP server — KB recall is memory_search against
the memory server, scoped to the KB wing via wing=<BIFROST_KB_WING>. No wing
name is assumed by default, so KB recall stays off until you set
BIFROST_KB_WING to match your gateway's knowledgebase scope.
Install
Get your gateway /mcp URL and personal virtual key (vk_…) from your gateway
operator, then:
Recommended — marketplace install (3 steps)
- In Claude Code:
/plugin marketplace add neXenio/bifrost-plugin /plugin install bifrost-plugin@bifrost-marketplace - Answer the install prompt with your gateway URL and virtual key. Only set env vars if you need an override or a non-default skill-server name (see Persisting env vars).
- Enable and restart Claude Code:
/plugin enable bifrost-plugin
To pick up a new plugin release:
/plugin marketplace update bifrost-marketplace
/plugin install bifrost-plugin@bifrost-marketplace
Persisting env vars
Claude Code does not read ~/.zshrc when launched from the Dock or Spotlight.
Use ~/.claude/settings.json so vars apply on every launch:
{
"env": {
"BIFROST_URL": "https://<your-gateway-host>/mcp",
"BIFROST_VK": "vk_<your-key>",
"BIFROST_SKILLS_SERVER": "skills"
}
}
Also add the same exports to ~/.zshrc (or ~/.bashrc) if you use the gateway
from a terminal. Restart Claude Code after editing settings.
Example shell profile lines:
echo 'export BIFROST_URL=https://<your-gateway-host>/mcp' >> ~/.zshrc
echo 'export BIFROST_VK=vk_<your-key>' >> ~/.zshrc
echo 'export BIFROST_SKILLS_SERVER=skills' >> ~/.zshrc # if not "skills"
source ~/.zshrc
The plugin ships a .mcp.json, so the bifrost MCP server wires itself from
the gateway URL and virtual key you enter in the install-time plugin config
prompt, no installer script and no shell env vars needed. It ships
enabled (defaultEnabled: true), so installing it activates it right
away. Leave the virtual key blank at the install prompt and it stays inert —
no key means no gateway connection. /plugin disable bifrost-plugin turns it
off. Type "set up bifrost" or /bifrost-onboard for a guided walkthrough,
/bifrost-debug if something's off.
Gateway skill discovery vs Bifrost Skills Repository
These are two different skill paths — do not confuse them:
| Path | How skills are accessed | Typical use |
|---|---|---|
MCP skill server (skills-skill_search, get_skill) |
Runtime search over the gateway's skill index | What this plugin nudges you to use before non-trivial work |
| Bifrost Skills Repository marketplace | <gateway>/api/skills/serve/claude-code/.claude-plugin/marketplace.json |
Install individual skills as Claude Code plugins (bifrost-<skill-name>) |
A skill published in the Bifrost dashboard may appear in the repository marketplace
before it is ingested into the MCP skill index. If get_skill says a repository
skill does not exist but the admin UI shows it, the MCP index may be stale — use
the admin Bump all-skills version control or install the skill directly from
the repository marketplace. See Bifrost Skills Repository docs.
Fallback — manual installer
If you can't use the marketplace (air-gapped, etc.), clone and run the installer,
a thin wrapper that registers the server through Claude Code's own CLI
(claude mcp add --scope user) — it never edits config files directly:
git clone https://github.com/neXenio/bifrost-plugin
cd bifrost-plugin
export BIFROST_URL=https://<your-gateway-host>/mcp
node scripts/install.js --key vk_<your-key> # then persist env vars as above
node scripts/install.js --dry-run # prints the claude mcp add command instead
macOS: Prefer
~/.claude/settings.json(see above) over shell profile alone. Dock/Spotlight launches do not inherit~/.zshrc.
Requirements
- Node.js 22.x, 24.x or 26.x on PATH, using the latest patch release; other major lines are unsupported. Node.js 26 LTS is recommended.
- Claude Code, or Claude Desktop, or claude.ai on the web
- Your gateway's
/mcpendpoint and a virtual key from your gateway operator, entered at the install prompt - If your gateway exposes a luca-memory server: v0.42 or later. v0.42 renamed and
folded its tools with no compatibility aliases, and the plugin sends only that shape.
Against an older server the memory features go silently empty —
/bifrost-debugsection 8 covers how to spot it. Skills and the rest of the gateway are unaffected.
Skills
| Skill | Trigger |
|---|---|
bifrost-onboard |
"set up bifrost", "onboard me to bifrost", "install bifrost gateway" |
bifrost-debug |
"bifrost not working", "mcp not connecting", "skills not found" |
bifrost-mcp-setup |
"manually add bifrost mcp", "edit mcp.json for bifrost", "installer failed" |
bifrost-code-mode |
"executeToolCode", "code mode", "listToolFiles", "how do I call gitlab through the gateway" |
bifrost-gateway-essentials |
Always loaded — carries the core operating rules for surfaces where hooks don't run |
bifrost-gateway-essentials exists for a specific gap. The SessionStart hook
injects a gateway-specific context block naming your real servers, skill library
and memory corpus on Claude Code. Cowork supports hooks at the host level, but
this plugin's MCP connection there remains unverified. Chat does not run hooks.
Skill descriptions are loaded on every surface whether or not the skill is
invoked, so that skill's description carries the parts that matter most —
above all that a missing <prefix><server>-<tool> usually means the
capability is in code mode behind executeToolCode, not that it is absent.
That is a partial substitute, not an equal one. A description can state the shape; it cannot name your gateway's actual servers, because those are discovered at runtime. The gateway's own MCP tool descriptions are served by the upstream MCP servers and are not something this plugin can rewrite.
Memory candidates
During a session the Stop hook periodically asks whether anything is worth
remembering. Findings are appended to .bifrost/candidates.md in the project
root, which the hook creates git-ignored on first use.
Candidates are local and unreviewed. Nothing is shared until someone promotes it:
/bifrost-candidates # review, promote the good ones, prune the rest
They deliberately do not go straight into shared memory. The corpus has no read
permission model — memory_search takes filters, but they are the caller's own
retrieval narrowing, not an ACL the writer can set — so anything written to it is
recalled by every colleague immediately as settled team knowledge. A mid-session
judgement should not become company-wide fact without a human deciding it should.
What may be promoted, and what has to be redacted or withheld, is set out in
guidance/memory-classification.md; the
/bifrost-candidates triage step applies it.
Nothing is written automatically, and answering "nothing worth recording" is a normal outcome. Delete the file at any time; it regenerates empty.
bifrost-plugin MCP questions
How do I install the bifrost-plugin in Claude Code?
You can install it by running /plugin marketplace add neXenio/bifrost-plugin followed by /plugin install bifrost-plugin in the CLI.
What is required for skill discovery and memory features to work?
These features require a gateway that exposes a skill server and/or a memory server; otherwise, the plugin will degrade gracefully and these features will no-op.
Does the plugin work on the Claude.ai web chat?
Yes, but certain features like memory auto-injection, skill-discovery hints, and usage tracking do not run on the web chat because they are hook-driven.