Deerdawn MCP Server

Model Context Protocol (MCP) server for the Deerdawn policy decision engine. Lets any MCP-compatible AI coding agent interact with your Deerdawn policies, evaluate decisions, debug policy logic, and generate compliance reports.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (GitHub Copilot / Continue), Zed, and any other agent that speaks MCP.

Features

• 15 Tools for policy management, decision evaluation, escalations, and analytics
• 6 Resources providing real-time access to policies, decisions, templates, and audit logs
• 5 Prompt Templates for debugging, policy creation, escalation review, pattern analysis, and compliance reporting
• Smart Caching to reduce API calls and improve performance
• Automatic Retries with exponential backoff for resilient operation
• Type-Safe with full TypeScript support

Prerequisites

You'll need a Deerdawn API key before installation.

1. Sign in at app.deerdawn.com
2. Go to Settings → API Keys → Create Key
3. Copy the key — it will start with dd_sandbox_ (sandbox) or dd_prod_ (production)

Your API key is scoped to one organization. If you belong to multiple orgs, you'll also need your DEERDAWN_ORG_ID from Settings → Organization.

Installation

npm install -g @deerdawn/mcp-server

Or run without installing via npx -y @deerdawn/mcp-server (recommended for most configs below).

Configuration

All agents use the same environment variables. The only difference is where the config file lives.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DEERDAWN_API_URL | Yes | https://api.deerdawn.com | Deerdawn API base URL | | DEERDAWN_API_KEY | Yes | — | Your Deerdawn API key (dd_sandbox_... or dd_prod_...) | | DEERDAWN_ORG_ID | No | — | Required only if your key has access to multiple orgs. Find it in Dashboard → Settings → Organization. | | DEERDAWN_ENVIRONMENT | No | sandbox | sandbox or production | | DEERDAWN_CACHE_ENABLED | No | true | Enable response caching | | DEERDAWN_CACHE_TTL_SECONDS | No | 60 | Cache TTL in seconds |

Claude Desktop

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

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com",
        "DEERDAWN_API_KEY": "dd_prod_your_api_key_here",
        "DEERDAWN_ORG_ID": "org-abc123",
        "DEERDAWN_ENVIRONMENT": "production"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add deerdawn npx -- -y @deerdawn/mcp-server

Then set env vars in your shell or .env:

export DEERDAWN_API_KEY=dd_prod_your_api_key_here
export DEERDAWN_API_URL=https://api.deerdawn.com

Cursor

macOS/Linux: ~/.cursor/mcp.json Windows: %APPDATA%\Cursor\mcp.json

Or via Cursor Settings → MCP → Add Server:

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com",
        "DEERDAWN_API_KEY": "dd_prod_your_api_key_here",
        "DEERDAWN_ORG_ID": "org-abc123",
        "DEERDAWN_ENVIRONMENT": "production"
      }
    }
  }
}

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json Windows: %APPDATA%\Codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com",
        "DEERDAWN_API_KEY": "dd_prod_your_api_key_here",
        "DEERDAWN_ORG_ID": "org-abc123",
        "DEERDAWN_ENVIRONMENT": "production"
      }
    }
  }
}

VS Code (GitHub Copilot / Continue)

Add to your workspace .vscode/settings.json or user settings.json:

{
  "mcp": {
    "servers": {
      "deerdawn": {
        "command": "npx",
        "args": ["-y", "@deerdawn/mcp-server"],
        "env": {
          "DEERDAWN_API_URL": "https://api.deerdawn.com",
          "DEERDAWN_API_KEY": "dd_prod_your_api_key_here",
          "DEERDAWN_ORG_ID": "org-abc123",
          "DEERDAWN_ENVIRONMENT": "production"
        }
      }
    }
  }
}

For Continue (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "deerdawn",
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com",
        "DEERDAWN_API_KEY": "dd_prod_your_api_key_here",
        "DEERDAWN_ORG_ID": "org-abc123",
        "DEERDAWN_ENVIRONMENT": "production"
      }
    }
  ]
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "deerdawn": {
      "command": {
        "path": "npx",
        "args": ["-y", "@deerdawn/mcp-server"],
        "env": {
          "DEERDAWN_API_URL": "https://api.deerdawn.com",
          "DEERDAWN_API_KEY": "dd_prod_your_api_key_here",
          "DEERDAWN_ORG_ID": "org-abc123",
          "DEERDAWN_ENVIRONMENT": "production"
        }
      }
    }
  }
}

Verify Installation

After saving your config and restarting your agent, ask it:

"List my Deerdawn policies"

If the MCP server connected successfully, it will fetch and display your policies. If you get a tool error instead, check:

• DEERDAWN_API_KEY is set and starts with dd_
• Your agent was fully restarted (not just reloaded)
• MCP server logs: ~/Library/Logs/Claude/mcp*.log (Claude Desktop) or equivalent for your agent

Available Tools

Decision Evaluation

evaluate_decision

Evaluate an action against your organization's policies. Returns allow, deny, or escalate.

{
  "action_type": "payment.process",
  "trace_id": "trace-123",
  "actor": { "id": "user-456", "role": "customer" },
  "target": { "type": "payment", "id": "pay-789" },
  "payload": { "amount": 5000, "currency": "USD" },
  "environment": "production"
}

get_decision · list_decisions · get_decision_stats

Retrieve, query, and analyze decision history.

Policy Management

list_policies · create_policy · update_policy · delete_policy

Full CRUD for policies.

get_policy_versions

Immutable version history for a policy.

create_policy_from_template

Create a policy from a built-in template.

Escalation Management

list_escalations · get_escalation · resolve_escalation

List, inspect, and approve/deny escalations.

Organization

get_organization_settings · update_organization_settings

Read and update org-level config (fail mode, redaction mode, etc).

Available Resources

| URI | Description | |-----|-------------| | deerdawn://policies/current | Active policies | | deerdawn://decisions/recent | Last 100 decisions | | deerdawn://templates/all | Policy templates | | deerdawn://registry/actions | Action type definitions | | deerdawn://audit/recent | Recent audit log entries | | deerdawn://escalations/pending | Pending escalations |

Prompt Templates

| Name | Description | |------|-------------| | debug-decision | Debug why a decision was allowed/denied/escalated | | create-policy | AI-assisted policy creation | | review-escalations | Review and bulk-process the escalation queue | | analyze-patterns | Detect anomalies in decision patterns | | compliance-report | Generate a compliance audit report |

Architecture

Any MCP-Compatible Agent (Claude, Cursor, Windsurf, VS Code, Zed, ...)
         ↓ (MCP Protocol — stdio)
Deerdawn MCP Server (TypeScript, npx @deerdawn/mcp-server)
         ↓ (HTTPS — REST API)
Deerdawn API (Node.js/Express)
         ↓
PostgreSQL + Redis

Troubleshooting

Server won't start

1. Verify DEERDAWN_API_KEY starts with dd_
2. Confirm DEERDAWN_API_URL is reachable
3. Check your agent's MCP server logs:
   • Claude Desktop: ~/Library/Logs/Claude/mcp*.log
   • Cursor: View → Output → MCP
   • Windsurf: Help → Toggle Developer Tools → Console
   • VS Code: Output panel → MCP
   • Zed: Help → Toggle Dev Tools → Console

Tools not appearing

Restart your editor/agent after saving the config file.

Authentication failed

Ensure the API key is set correctly — it must start with dd_prod_ or dd_sandbox_.

Slow responses

Enable caching: DEERDAWN_CACHE_ENABLED=true

Development

npm install
npm run build   # compile TypeScript
npm run dev     # watch mode
npm test        # run tests
npm run lint

License

MIT