@vantageos/vantage-registry-mcp

MCP server exposing VantageRegistry Convex functions as Claude Code tools via stdio transport.

Version: 1.8.0 Backend: Convex (vibrant-ibex-858) Transport: stdio (Claude Code MCP protocol)

Installation

Add to your Claude Code MCP config (.claude/mcp.json or equivalent):

{
  "mcpServers": {
    "vantage-registry": {
      "command": "bunx",
      "args": ["@vantageos/[email protected]"],
      "env": {
        "CONVEX_URL": "https://vibrant-ibex-858.convex.cloud",
        "VR_ADMIN_WRITE_SECRET": "<your-write-secret>"
      }
    }
  }
}

Pin @1.8.0 in args so bunx does not serve a cached older version. Or set CONVEX_URL in .env.local at the repo root.

What's new in 1.8.0

| Feature | Details | |---------|---------| | doc-binary template type | upsert_template accepts template_type="doc-binary" plus 4 new optional fields: renderer_kind, input_schema, assets, output_formats | | 4 template_consumers tools | link_template_consumer, unlink_template_consumer, list_consumers_for_template, list_templates_for_consumer — junction table linking templates to the components/BUs that consume them | | 3 Bible fields on components | consumers, clientReadyStage, and lastUsageSignal now returned by list_components / get_component |

Tools

Teams

| Tool | Description | |------|-------------| | upsert_team | Create or update a team (upsert by name) | | list_teams | List all teams — optional status filter | | get_team | Get a team by Convex document ID |

Agents

| Tool | Description | |------|-------------| | upsert_agent | Create or update an agent (upsert by name) | | list_agents | List agents — optional status / team filters | | list_agents_by_team | List agents for a specific team | | get_agent | Get an agent by Convex document ID |

Skills

| Tool | Description | |------|-------------| | upsert_skill | Create or update a skill (upsert by name). New in 1.6.0: optional vrBody writes the full SKILL.md body (vrContent/hash/version) in the same call | | list_skills | List skills — optional status / team / category filters | | list_skills_by_team | List skills for a specific team | | list_skills_by_category | List skills for a specific category | | get_skill | Get a skill by Convex document ID |

Plugins

| Tool | Description | |------|-------------| | upsert_plugin | Create or update a plugin (upsert by name) | | list_plugins | List plugins — optional status filter | | get_plugin | Get a plugin by Convex document ID |

Hooks

| Tool | Description | |------|-------------| | upsert_hook | Create or update a hook (upsert by name). New in 1.6.0: optional tests array of hook test file paths | | list_hooks | List hooks — optional status / event / scope filters | | get_hook | Get a hook by Convex document ID |

Prompts

| Tool | Description | |------|-------------| | upsert_prompt | Create or update a prompt (upsert by name) | | list_prompts | List prompts — optional status / team filters | | get_prompt | Get a prompt by Convex document ID |

Templates

| Tool | Description | |------|-------------| | upsert_template | Create or update a template (upsert by name). New in 1.8.0: template_type="doc-binary" + 4 doc-binary fields | | list_templates | List templates — optional team and template_type filters | | get_template | Get a template by Convex document ID | | detect_template_drift | Return per-template contentHash + provenance for drift comparison | | list_templates_by_category | List templates for a specific category (uses byCategory index) |

template_type enum (all values):

"standard" | "mission" | "brief" | "runbook" | "document" | "checklist" | "doc-binary"

doc-binary template type (new in 1.8.0)

Use template_type="doc-binary" for Living Bible binary document templates. Four additional optional fields become meaningful:

| Field | Type | Description | |-------|------|-------------| | renderer_kind | string | Renderer identifier — e.g. "pdf", "docx", "html" | | input_schema | string | JSON-encoded schema string describing template inputs | | assets | object | Asset URLs: { icon?, banner?, thumbnail? } | | output_formats | string[] | Supported output formats — e.g. ["pdf", "docx"] |

Example: upsert a doc-binary template

upsert_template(
  name="employee-contract-v2",
  team="hephaistos",
  purpose="Generates employee contract PDFs from structured input",
  content="# Employee Contract\n\n{{name}}, {{start_date}}...",
  version="1.0.0",
  template_type="doc-binary",
  category="hr/contracts",
  renderer_kind="pdf",
  input_schema="{\"name\":{\"type\":\"string\"},\"start_date\":{\"type\":\"string\"}}",
  assets={"icon": "https://cdn.example.com/icons/contract.svg"},
  output_formats=["pdf", "docx"]
)

Template Consumers (new in 1.8.0)

The template_consumers junction table links templates to the components/BUs that consume them. This enables the Living Bible pattern — tracking which consumers depend on each doc-binary template.

Link type semantics (linkType):

• "uses" — consumer actively consumes/renders this template
• "produces" — consumer generates output documents from this template
• "references" — informational cross-reference

| Tool | Type | Description | |------|------|-------------| | link_template_consumer | write | Upsert a link by (templateId, consumerName). Returns {linkId, created: true} on insert, {linkId, created: false} on update | | unlink_template_consumer | write | Hard-delete the link by (templateId, consumerName). Returns {unlinked: true} if found, {unlinked: false} if not | | list_consumers_for_template | read | List all consumers for a template — returns link objects with consumerName, consumerBU, consumerComponentId, linkType, createdAt. Optional linkType filter | | list_templates_for_consumer | read | Reverse lookup — enriched [{link, template}] for a consumerName. Optional linkType filter. Orphaned links skipped |

link_template_consumer params:

| Param | Type | Required | Description | |-------|------|----------|-------------| | templateId | string | yes | Convex document ID of the template | | consumerName | string | yes | Stable slug identifying the consumer — e.g. "hephaistos-doc-forge" | | consumerBU | string | no | Business unit slug — e.g. "hephaistos", "sigma", "omega" | | consumerComponentId | string | no | Convex document ID of the component row (omit for BU-level consumers without a registered components row) | | linkType | string | no | "uses", "produces", or "references" — omit to leave untyped | | createdBy | string | no | Orchestrator or script creating this link — e.g. "omega" |

unlink_template_consumer params:

| Param | Type | Required | Description | |-------|------|----------|-------------| | templateId | string | yes | Convex document ID of the template | | consumerName | string | yes | Slug identifying the consumer |

list_consumers_for_template params:

| Param | Type | Required | Description | |-------|------|----------|-------------| | templateId | string | yes | Convex document ID of the template | | linkType | string | no | Filter by link type — omit to return all |

list_templates_for_consumer params:

| Param | Type | Required | Description | |-------|------|----------|-------------| | consumerName | string | yes | Slug identifying the consumer | | linkType | string | no | Filter by link type — omit to return all |

Example invocations:

# Link a consumer to a template
link_template_consumer(
  templateId="j57abc123...",
  consumerName="hephaistos-doc-forge",
  consumerBU="hephaistos",
  linkType="uses",
  createdBy="omega"
)

# Remove a consumer link
unlink_template_consumer(templateId="j57abc123...", consumerName="hephaistos-doc-forge")

# Who consumes this template?
list_consumers_for_template(templateId="j57abc123...")

# What templates does this consumer use?
list_templates_for_consumer(consumerName="hephaistos-doc-forge", linkType="uses")

Runbooks

Added in 1.1.0. Runbooks are structured, versioned operational playbooks stored in VantageRegistry.

| Tool | Description | |------|-------------| | upsert_runbook | Create or update a runbook (upsert by name) | | get_runbook | Get a runbook by slug — optionally guard by version | | list_runbooks | List runbooks — optional status, category, team, applicability filters | | list_runbooks_by_category | List runbooks for a specific category (uses byCategory index) | | list_runbooks_by_team | List runbooks for a specific team (uses byTeam index) | | delete_runbook | Soft-delete a runbook — sets status to deprecated | | detect_runbook_drift | Return per-runbook vrHash (sha256 of content) + category + version for drift comparison (added in 1.6.0) |

Runbook status values: draft | published | deprecated

Example invocations:

# Get a specific runbook
get_runbook(name="deploy-production", version="1.0.0")

# List all published deployment runbooks
list_runbooks(status="published", category="deployment")

# List all runbooks for the core team
list_runbooks_by_team(team="core")

# List all published runbooks in the quality category
list_runbooks_by_category(category="quality", status="published")

# Soft-delete a runbook
delete_runbook(name="old-process-v1")

Upsert a runbook (minimal example):

upsert_runbook(
  name="onboard-agent",
  description="Standard protocol to onboard a new agent to the fleet",
  version="1.0.0",
  status="draft",
  category="onboarding",
  tags=["agent", "onboarding", "fleet"],
  content="# Onboard Agent\n\n...",
  phases=[{ name="prep", description="Preparation phase", steps=[], gate=null }],
  inputs=[],
  outputs=[],
  applicability={ orchestrators=["omega"], business_units=[], use_cases=[] },
  author="omega",
  team="core",
  related_skills=[],
  related_agents=[],
  linked_templates=[]
)

Components Catalog

| Tool | Description | |------|-------------| | register_component | Create or update a component (upsert by name+kind) | | list_components | List components — optional kind, ownerTeam, status, tags filters. New in 1.8.0: response includes consumers, clientReadyStage, lastUsageSignal | | get_component | Get a component by Convex document ID. New in 1.8.0: response includes consumers, clientReadyStage, lastUsageSignal | | search_components | Search components by name prefix | | update_component | Patch individual fields on an existing component | | delete_component | Soft-delete a component — sets status to deprecated |

Component Bible fields (new in 1.8.0)

Three fields are now surfaced in list_components and get_component responses:

| Field | Type | Description | |-------|------|-------------| | consumers | string[] | Downstream orchestrators / agents that consume this component — e.g. ["omega", "sigma"] | | clientReadyStage | string | Readiness stage for client-facing exposure: "internal-only", "dogfood", "private-beta", or "public-cloud-paid" | | lastUsageSignal | object | Latest usage signal: { source, value, capturedAt, raw? } — auto-updated on each get_component / list_components call when VR_ADMIN_WRITE_SECRET is configured |

These fields can be set via register_component or update_component:

register_component(
  name="check-messages",
  kind="skill",
  status="active",
  ownerTeam="core",
  consumers=["omega", "pi", "sigma"],
  clientReadyStage="internal-only"
)

Stats

| Tool | Description | |------|-------------| | get_stats | Registry overview — counts per table including runbooks breakdown |

get_stats response shape:

{
  "teams": 18,
  "agents": 148,
  "skills": 328,
  "plugins": 16,
  "hooks": 22,
  "runbooks_count": {
    "total": 12,
    "by_status": {
      "draft": 3,
      "published": 8,
      "deprecated": 1
    },
    "by_category": {
      "deployment": 4,
      "quality": 4,
      "onboarding": 4
    }
  },
  "total": 544
}

Schema

template_consumers table (new in 1.8.0)

| Field | Type | Notes | |-------|------|-------| | templateId | Id<"templates"> | Foreign key — template being consumed | | consumerName | string | Stable slug identifying the consumer | | consumerBU | string? | Business unit slug — e.g. "hephaistos" | | consumerComponentId | Id<"components">? | Optional FK to components row | | linkType | "uses" \| "produces" \| "references"? | Semantic relationship type | | createdAt | number | Unix timestamp (ms) | | createdBy | string? | Orchestrator or script that created this link |

Indexes: byTemplate, byConsumer, byTemplateAndConsumer (composite — enforces at-most-one link per pair)

runbooks table (new in 1.1.0)

| Field | Type | Notes | |-------|------|-------| | name | string | Unique slug — upsert key | | description | string | Purpose summary | | version | string | Semantic version | | status | draft \| published \| deprecated | Lifecycle state | | category | string | e.g. deployment, quality, onboarding | | tags | string[] | Searchable tags | | content | string | Full markdown content | | phases | Phase[] | Ordered phases with steps and gates | | inputs | RunbookInput[] | Required input parameters | | outputs | RunbookOutput[] | Produced output artifacts | | applicability | object | orchestrators, business_units, use_cases slugs | | author | string | Author slug | | team | string | Owning team slug | | related_skills | string[] | Referenced skill slugs | | related_agents | string[] | Referenced agent slugs | | linked_templates | LinkedTemplate[] | Templates used within this runbook |

Indexes: byName, byStatus, byCategory, byTeam

templates table

template_type discriminator field — all values as of 1.8.0:

| Value | Description | |-------|-------------| | standard | Standard template | | mission | Mission brief template | | brief | Agent/task brief | | runbook | Runbook template | | document | Free-form document | | checklist | Checklist template | | doc-binary | Living Bible binary document template (new in 1.8.0) — use with renderer_kind, input_schema, assets, output_formats |

components table — Bible fields (new in 1.8.0)

| Field | Type | Notes | |-------|------|-------| | consumers | string[]? | Downstream orchestrators / agents that consume this component | | clientReadyStage | string? | "internal-only" | "dogfood" | "private-beta" | "public-cloud-paid" | | lastUsageSignal | object? | { source, value, capturedAt, raw? } — auto-updated on every read |

Requirements

• Bun runtime (server is authored in TypeScript for Bun)
• CONVEX_URL environment variable pointing to the VantageRegistry Convex deployment (use .convex.cloud URL, not .convex.site)

ADMIN mode vs read-only mode (new in 1.7.0)

The MCP server operates in one of two modes depending on token configuration:

ADMIN mode (write operations enabled)

Requires both environment variables:

MCP_BEARER_TOKEN=<admin-token>       # HTTP transport only — identifies admin callers
VR_ADMIN_WRITE_SECRET=<secret>       # backend write guard secret (from PR #93)

Write tools (upsert_*, delete_*, register_component, update_component, link_runbook_template, unlink_runbook_template, link_template_consumer, unlink_template_consumer) inject adminSecret into every Convex mutation call server-side. adminSecret is never exposed in tool input schemas — clients do not provide it.

Read-only mode (write operations refused)

When the server is configured with MCP_BEARER_TOKEN_READONLY only (no admin token), all write tool calls are refused:

• HTTP transport: returns 403 Forbidden before the handler executes.
• stdio transport: adminWriteArgs() throws immediately — zero mutations fired.

A read-only instance cannot be made to write even if VR_ADMIN_WRITE_SECRET is present in its environment. The ADMIN mode gate is checked before the secret is injected.

Write tool list (all require ADMIN mode + VR_ADMIN_WRITE_SECRET)

upsert_team, upsert_agent, upsert_skill, upsert_skill_content, upsert_agent_content, upsert_plugin_content, upsert_hook_content, upsert_command_content, upsert_plugin, upsert_hook, upsert_prompt, upsert_template, upsert_test_run, upsert_skill_eval_corpus, upsert_runbook, delete_runbook, link_runbook_template, unlink_runbook_template, link_template_consumer, unlink_template_consumer, register_component, update_component, delete_component

Read tool list (work in both modes, no secret required)

All list_*, get_*, detect_*, search_components, get_stats.

Changelog

See CHANGELOG.md in this directory.

Orchestrator: Omega — VantageOS Team | 2026-06-18