Claude Desktop MCP

vybdocs ships a Model Context Protocol (MCP) server that connects Claude Desktop to your project's constraint spec. It lets you propose new rules, dry-run them against your codebase, commit them, and read your current spec — all using natural language.

Starting the MCP server

vyb mcp

This starts the vybdocs MCP server on a local socket. Leave it running while using Claude Desktop.

vybdocs MCP server
  Spec:     /your-project/.vyb/spec.yaml
  Socket:   /tmp/vyb-mcp.sock
  Ready.

Connecting to Claude Desktop

1. Open Claude Desktop → Settings → Developer → Model Context Protocol
2. Add a new server:
   • Name: vybdocs
   • Transport: stdio
   • Command: vyb mcp --stdio
   • Working directory: your project root

Or, add it to your claude_desktop_config.json directly:

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vybdocs": {
      "command": "vyb",
      "args": ["mcp", "--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

Restart Claude Desktop. You should see "vybdocs" listed in the tool panel.

MCP tools

The vybdocs MCP server exposes 5 tools:

proposeRule

Propose a new rule definition. Claude generates the rule YAML from a natural language description and returns it for review.

Inputs:

• description — natural language description of the constraint
• category — which category the rule belongs to
• severity — suggested severity (info, warn, block)
• examples — optional: code examples that should trigger the rule

Example interaction:

User: We want to ban the use of the 'moment' package across our codebase.
      Engineers should use date-fns instead.

Claude: [calls proposeRule]

  Proposed rule:
  ─────────────────────────────────────────
  id: pkg-moment-ban
  category: dependencies
  name: no-moment
  description: >
    moment.js is in maintenance mode and adds 67kB gzipped.
    Use date-fns instead.
  severity: warn
  pattern: "from 'moment'|require\\('moment'\\)"
  remediation: >
    Replace moment.js with date-fns.
    import { format, parseISO } from 'date-fns'
    All moment() calls have date-fns equivalents.
  ─────────────────────────────────────────

  Shall I run a dry-run to see how many violations exist?

dryRunRule

Run a proposed (or existing) rule against the current codebase without committing anything. Reports violations by file and line.

Example interaction:

User: Yes, dry-run it.

Claude: [calls dryRunRule with the proposed rule]

  Dry run: pkg-moment-ban
  ─────────────────────────────────────────
  Files scanned: 47
  Violations: 3

    src/utils/date.ts:1        import moment from 'moment'
    src/components/Chart.tsx:5 import moment from 'moment'
    package.json:14            "moment": "^2.29.4"

  3 violations. The package.json match is expected (it's the
  dependency declaration). The other 2 are import statements
  that need to be migrated.
  ─────────────────────────────────────────

  Ready to commit this rule? Or would you like to adjust the
  severity or add exclusions first?

commitRule

Commit an approved rule to .vyb/spec.yaml. Subject to the one-way ratchet — cannot downgrade existing rule severities.

Example interaction:

User: Commit it. Add an exclusion for package.json so that match
      doesn't show up in check output.

Claude: [calls commitRule]

  Committed rule: pkg-moment-ban
  ─────────────────────────────────────────
  Written to: .vyb/spec.yaml (dependencies.rules)
  Pack version: not applicable (custom rule, not in a pack)
  Exclusions added: ["package.json", "package-lock.json"]

  Rule is now active. Next vyb check run will evaluate it.
  Recommend: ask the team to migrate the 2 import violations
  before the next sprint.
  ─────────────────────────────────────────

readSpec

Read the current spec and describe what is configured — useful for auditing your current rule set or asking Claude to suggest improvements.

Example interaction:

User: Read my current spec and tell me if there are any gaps
      for a SOC 2 Type II audit.

Claude: [calls readSpec]

  Spec summary: acme-platform
  ─────────────────────────────────────────
  Rules active: 24  (8 block, 14 warn, 2 info)
  Frameworks mapped: soc2, eu-ai-act

  SOC 2 gaps I can identify:
  • CC6.7 (transmission security) — no rules ban HTTP for
    external API calls. Recommend adding sec-http-ban at block.
  • CC7.2 (system monitoring) — no rules require audit log
    annotations on sensitive operations. Consider adding a
    require-audit-log rule for database write operations.
  • CC9.2 (risk assessment) — no rules govern third-party
    dependency vulnerability scanning.

  Want me to propose rules for any of these gaps?
  ─────────────────────────────────────────

suggestPack

Given your project's language, framework, and compliance requirements, suggest which built-in pack to apply or which custom rules to add.

Example interaction:

User: We're a Next.js app, TypeScript, Postgres, hosted on AWS,
      and we're starting a SOC 2 audit.

Claude: [calls suggestPack]

  Recommendation: us-saas-general pack

  For SOC 2 Type II with your stack, I recommend:
  1. Apply us-saas-general as your base pack
  2. Add these stack-specific rules:
     • no-eval (block) — already in pack
     • no-hardcoded-aws-credentials (block) — AWS-specific
     • no-console-log-in-handlers (warn) — Next.js API routes
     • require-prisma-transactions (info) — data integrity

  Run: vyb init --pack us-saas-general

The one-way ratchet in MCP

The MCP server enforces the one-way ratchet. If you try to downgrade a rule severity through Claude:

User: Change no-eval from block to warn.

Claude: [calls commitRule with severity: warn]

  Error: Cannot downgrade severity of sec-001 (no-eval)
  from block to warn.

  The one-way ratchet is active (allow-severity-downgrade: false
  in your spec settings). This prevents LLMs from softening
  compliance-critical rules.

  To downgrade a rule, a human must edit the spec file directly
  and run: vyb pack --emit --allow-downgrade

Security considerations

The MCP server only reads and writes .vyb/spec.yaml and .vyb/packs/. It does not execute code, make network requests, or access files outside the project root.

All commits made via commitRule are recorded in git as a normal file change with the author as whoever ran vyb mcp. The Evidence Pack logs MCP-sourced commits distinctly from human-authored ones.

---

Next: Cursor Integration