Cursor & Claude Desktop Local Integration Guide

Once business vertical slices are exposed via the Model Context Protocol (MCP) in BitzOrcas.Modern, developers can interact with the system directly through AI clients (such as Cursor IDE in Agent Mode or Anthropic Claude Desktop). Through natural language prompts, agents can query operational records, trigger workflows, and execute mutations safely.

This guide walks you through establishing and testing this client connection in under five minutes.

1. Start the Local BitzOrcas Host

Start BitzOrcas.Api using .NET Aspire or standard CLI commands:

# Launch the API host listening on http://127.0.0.1:5000
dotnet run --project src/Hosts/BitzOrcas.Api

Verify that the MCP streamable transport route is responsive:

curl -I http://127.0.0.1:5000/mcp
# Returns HTTP/1.1 200 OK or 401/403 (when strict authentication challenges apply)

2. Configure Cursor IDE (Agent Mode)

Cursor natively supports Model Context Protocol servers configured via .cursor/mcp.json in the workspace root or global IDE preferences.

Create or update .cursor/mcp.json in your repository root:

{
  "mcpServers": {
    "bitzorcas-local": {
      "url": "http://127.0.0.1:5000/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer dev_token_administrator_seed",
        "X-Tenant-Id": "1000001"
      }
    }
  }
}

After saving the configuration, open Cursor Settings -> Features -> MCP:

1. Confirm that bitzorcas-local displays a green status indicator (Connected);
2. Expand the tool catalog to verify that tools such as create_litigation_case and get_case_by_id appear with their corresponding JSON Schemas.

3. Configure Claude Desktop

For users of the official Anthropic Claude Desktop client, edit your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server definition:

{
  "mcpServers": {
    "bitzorcas": {
      "url": "http://127.0.0.1:5000/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer dev_token_administrator_seed",
        "X-Tenant-Id": "1000001"
      }
    }
  }
}

Save the file and restart Claude Desktop. The hammer (Tools) icon in the bottom right corner of the chat input will illuminate, revealing the BitzOrcas business tools available to the model.

4. Live Conversational Execution

Issue a natural language prompt in Cursor or Claude:

Developer Prompt: “Please create a litigation case for tenant 1000001: claim amount is 500,000 RMB, defendant is ‘Far East Construction Co., Ltd.’, title is ‘Commercial Construction Contract Default’, and set case type to CommercialArbitration.”

Autonomous Agent Flow

1. Intent Matching: The LLM discovers create_litigation_case in its active tool catalog, matching user intent;
2. Emitting Structured Tool Arguments:

   {
     "CaseTitle": "Commercial Construction Contract Default",
     "CaseType": "CommercialArbitration",
     "ClaimAmount": 500000,
     "DefendantName": "Far East Construction Co., Ltd."
   }

3. Pipeline Invariant Enforcement: The backend receives the request, ValidationPipelineBehavior confirms the amount is strictly positive, SqlSugarUnitOfWork persists the aggregate root, and the snowflake matter ID ARB-20260923-0012 is generated;
4. Model Summary Response:

   “The case has been successfully filed in the system:

   • Matter ID: ARB-20260923-0012
   • Title: Commercial Construction Contract Default
   • Claim: ¥500,000.00
   • Defendant: Far East Construction Co., Ltd.
   • Status: Initial lead attorney seat bound, filing workflow initiated.”

5. Troubleshooting Common Issues

6. Related Architecture Decisions & Deep Dives

• Security Governance: Agent Multi-Tenant Context & Human-in-the-Loop Approval
• Server Architecture: MCP Server Architecture & Compile-Time Generators
• ADR Reference: ADR 0205: Commercial Package Distribution & Extension Model