MCP Server

Integrations

Connect AI agents like Claude Desktop, Cursor, and Windsurf to your Arbtr decisions using the Model Context Protocol.

Arbtr exposes your team's decisions via the Model Context Protocol (MCP), allowing AI coding assistants to understand your architecture while they help you code.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants access external data sources. When connected to Arbtr, your AI can search decisions, understand relationships, and give architecture-aware suggestions.

Compatible AI Clients

Claude Code

Recommended

Anthropic's CLI for Claude. Supports MCP and Skills for automated governance.

Claude Desktop

Anthropic's desktop app for Claude with full MCP support.

Cursor

AI-first code editor with MCP integration for external context.

Windsurf

Codeium's IDE with MCP support for enhanced context.

Claude Code Plugin (Recommended)

The easiest way to integrate Arbtr with Claude Code is our official plugin. It includes the MCP server, governance skill, and automated hooks—all in one install.

What's Included

MCP Server — Claude can search decisions, check standards, and log choices
Governance Skill — Claude automatically checks Arbtr before architectural changes
Session Hooks — Context loaded at start, code checked on write, decisions captured at end

Quick Install:

# Add the marketplace and install
claude plugin marketplace add arbtr-software/claude-code-plugin
claude plugin install arbtr

# Set your API key
export ARBTR_API_KEY="mcp_arbtr_your_key_here"

Get your API key from Team Settings → AI Settings → MCP Integration. See the plugin repository for full documentation.

Manual Setup (Other Clients)

For Claude Desktop, Cursor, Windsurf, or other MCP clients, follow these steps to connect manually:

Enable MCP in Arbtr

Go to Team Settings
Navigate to AI Settings
Enable MCP Integration

Generate an API Key

Click Generate Key to create a team MCP API key. Copy and store it securely—you won't be able to see it again.

Format: mcp_arbtr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Configure Your AI Client

Add Arbtr to your AI client's MCP configuration. The exact location varies by client.

Claude Desktop (~/.config/claude/claude_desktop_config.json)

{
  "mcpServers": {
    "arbtr": {
      "url": "https://your-arbtr-instance.com/api/mcp",
      "headers": {
        "Authorization": "Bearer mcp_arbtr_your_key_here"
      }
    }
  }
}

Restart Your AI Client

Restart your AI client to load the new MCP configuration. You should now be able to ask about your team's decisions.

Decision Tools

Once connected, your AI assistant can use these tools to query your decisions:

search_decisions

Semantic search across all your team's decisions using AI embeddings.

Example: "Find decisions about authentication"

get_decision

Retrieve full details of a specific decision by its slug.

Example: "Show me the database-choice decision"

Search Implementation

search_decisions uses vector similarity search:

Query expansion: Short queries (<100 chars) are expanded with related terms using GPT-4o-mini
Embedding: Query is embedded using OpenAI text-embedding-3-small
Vector search: Cosine similarity against decision_embeddings table (pgvector)
Threshold: Default similarity threshold of 0.2, returns up to 20 results
Grouping: Results grouped by decision to avoid duplicate matches from multiple arguments

AI Memory Layer Tools

These tools enable AI agents to participate in your team's knowledge management:

get_project_context

Retrieve team standards and project memory for a repository. Use this at session start to give the AI full context about your team's conventions.

{
  "git_remote_url": "git@github.com:owner/repo.git",
  "compact": true  // Token-efficient format for LLM context
}

Returns: Team standards, project-specific patterns, relevant decisions, recent choices.

log_choice

Record an architectural choice made during development. These are aggregated into project memory over time.

{
  "git_remote_url": "git@github.com:owner/repo.git",
  "choice_type": "dependency",  // dependency | pattern | convention | structure | tool | architecture
  "description": "Use React Query for server state",
  "reasoning": "Reduces boilerplate, built-in caching",
  "category": "state_management",
  "confidence": 0.8
}

check_standards

Check if a proposed choice aligns with team standards before implementing.

{
  "proposed_choice": "use Redux for state management",
  "choice_type": "dependency"  // optional, for better matching
}

Returns: aligned: true/false, conflicts (if any), and suggestions based on existing standards.

Git Tools

If you have a Git provider connected (GitHub, GitLab, or Bitbucket), these additional tools let your AI assistant explore your codebase:

Git tools require a connected Git integration. Set up your Git provider in Team Settings → Integrations before using these tools.

git_search_prs

Search for Pull Requests or Merge Requests. Filter by state (open, closed, merged).

git_get_file

Read file contents from any branch. Useful for reviewing implementations.

git_get_pr_status

Check the status of a specific PR/MR by number (open, merged, or closed).

git_list_directory

Browse repository structure. Lists files and folders at a given path.

git_list_repos

List all accessible repositories. Discover what repos your team has access to.

git_search_code

Search for code patterns across repositories. Find where libraries are used.

Available Resources

AI clients can also access these read-only resources:

arbtr://decisions

List of all active decisions with titles, statuses, importance, and tags.

arbtr://decisions/{slug}

Full decision details including context, positions, arguments, and relationships.

arbtr://graph

The decision graph with all nodes, edges, and relationship types.

Example Conversations

Architecture-aware coding:

You:"I'm adding a new API endpoint. What database should I use?"

AI:"Based on your team's decisions, you use PostgreSQL for transactional data (see decision 'database-choice'). For caching, you've decided on Redis (see 'caching-strategy')."

Checking for conflicts:

You:"Can I use MongoDB for this new service?"

AI:"That would conflict with your 'single-database-technology' decision, which standardized on PostgreSQL to reduce operational complexity. Consider discussing with the team first."

Understanding context:

You:"Why do we use REST instead of GraphQL?"

AI:"According to the 'api-style' decision, your team chose REST because most developers were already familiar with it, and the caching benefits aligned with your CDN strategy. The decision was approved in October 2025."

Security & Privacy

Team-Scoped Access

Each API key is scoped to a single team. AI clients can only access decisions from the team that generated the key.

Read-Only Access

MCP provides read-only access. AI clients cannot create, modify, or delete decisions through the MCP interface.

Revocable Keys

API keys can be revoked at any time from Team Settings. Revoked keys stop working immediately.

Keep your API key secure. Anyone with the key can read your team's decisions. Don't commit it to version control or share it publicly.

Technical Details

Transport Protocol

Arbtr uses the Streamable HTTP transport from the MCP SDK:

POST /api/mcp — Handle JSON-RPC messages
GET /api/mcp — SSE stream for server-initiated messages
DELETE /api/mcp — Close session

Session IDs are returned in Mcp-Session-Id header and should be included in subsequent requests.

Access Logging

All MCP tool calls are logged to mcp_access_log:

Tool name, query, result count
Decision IDs and titles accessed
Error status and messages
Timestamp

View logs in the Pulse Dashboard under "AI Agent Activity".

Embedding Requirements

Semantic search requires decision embeddings. Embeddings are generated:

Automatically when decisions are created or updated
For both decision context and individual arguments
Using text-embedding-3-small (1536 dimensions)

Teams need at least 5 decisions for meaningful search results.

Claude Code Skill (Manual Install)

Recommended: Use the Arbtr Claude Code Plugin instead—it includes this skill plus MCP integration and automated hooks.

If you prefer to install just the governance skill without the full plugin, you can do so manually:

What the Skill Does

Searches Arbtr before significant code changes
Warns you if proposed changes conflict with accepted decisions
Suggests approved alternatives when conflicts are found
Reminds you to record significant architectural choices

Install for your project:

mkdir -p .claude/skills/arbtr-architectural-governance
curl -o .claude/skills/arbtr-architectural-governance/SKILL.md \
  https://arbtr.app/api/skills/arbtr-architectural-governance/skill
git add .claude/skills/ && git commit -m "Add Arbtr governance skill"

Or install globally:

mkdir -p ~/.claude/skills/arbtr-architectural-governance
curl -o ~/.claude/skills/arbtr-architectural-governance/SKILL.md \
  https://arbtr.app/api/skills/arbtr-architectural-governance/skill

After installing, restart Claude Code. The skill will activate automatically when you ask Claude to scaffold features, add libraries, or refactor code.

Troubleshooting

'Authentication failed'

Double-check your API key is correct and hasn't been revoked. Make sure the Authorization header uses the Bearer prefix.

'AI features not enabled'

MCP requires AI features to be enabled for your team. Go to Team Settings → AI Settings and ensure AI features are turned on.

Client not connecting

Make sure you've restarted your AI client after updating the MCP configuration. Check the client's logs for connection errors.

No decisions found

MCP only returns active decisions (not archived or draft). If your team has no active decisions, searches will return empty results.

Arbtr Code Tools

Back to

All Integrations

Command Palette