DeerDawn MCP Server

Never start cold. Every new AI session opens already briefed on your project.

DeerDawn is AI session memory — your AI's chief of staff — for Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, Codex, and any other MCP-compatible agent. Start a session anywhere and start_session hands the agent the brief: what you were working on, what was decided, and what's blocking — so no session starts cold.

Quick start

Step 1 — Get your API key

Sign in at app.deerdawn.com → Settings → API Keys → Create Key. Your key will start with dd_.

Step 2 — Add to your tool

Pick your editor below and paste in the config. Restart the tool.

Step 3 — Call start_session

At the beginning of any session, call start_session. You'll get the active project context and a map of everything else in one shot.

Configuration

Claude Code (CLI)

Run the setup command — it registers the server and handles sign-in in one step:

npx -y @deerdawn/mcp-server@latest setup

Or register manually (user scope so it works across all projects):

claude mcp add -s user deerdawn -e DEERDAWN_API_URL=https://api.deerdawn.com -- npx -y @deerdawn/mcp-server@latest

If you already have an API key, pass it directly:

claude mcp add -s user deerdawn \
  -e DEERDAWN_API_URL=https://api.deerdawn.com \
  -e DEERDAWN_API_KEY=dd_your_key_here \
  -- npx -y @deerdawn/mcp-server@latest

Restart Claude Code after registering. On first start, call get_auth_status if you haven't signed in yet — it returns a browser URL to complete sign-in.

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@latest"],
      "env": {
        "DEERDAWN_API_KEY": "dd_your_key_here"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_KEY": "dd_your_key_here"
      }
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_KEY": "dd_your_key_here"
      }
    }
  }
}

VS Code (GitHub Copilot / Continue)

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

{
  "mcp": {
    "servers": {
      "deerdawn": {
        "command": "npx",
        "args": ["-y", "@deerdawn/mcp-server@latest"],
        "env": {
          "DEERDAWN_API_KEY": "dd_your_key_here"
        }
      }
    }
  }
}

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

{
  "mcpServers": [
    {
      "name": "deerdawn",
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_KEY": "dd_your_key_here"
      }
    }
  ]
}

Zed

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

{
  "context_servers": {
    "deerdawn": {
      "command": {
        "path": "npx",
        "args": ["-y", "@deerdawn/mcp-server@latest"],
        "env": {
          "DEERDAWN_API_KEY": "dd_your_key_here"
        }
      }
    }
  }
}

Codex (OpenAI)

Open Settings → MCP Servers → Add Server:

• Command: npx
• Args: -y @deerdawn/mcp-server@latest
• Env: DEERDAWN_API_KEY = your key from app.deerdawn.com → Settings → API Keys

No API key yet? Add the server without DEERDAWN_API_KEY first, then call get_auth_status — it returns a browser sign-in URL. After signing in, your key is saved automatically.

Host naming note

Some MCP hosts expose tools with a server prefix (for example deerdawn-get_auth_status) instead of bare names (get_auth_status). If a tool name is not found, retry with the deerdawn- prefixed variant.

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DEERDAWN_API_KEY | Yes* | — | Your API key (dd_...). Get one at app.deerdawn.com → Settings → API Keys. | | DEERDAWN_API_URL | No | https://api.deerdawn.com | API base URL. Only change for self-hosted or staging. | | DEERDAWN_ENVIRONMENT | No | production | sandbox or production |

*Required unless using the browser device flow (see "No API key?" above).

Session memory tools

These are the core tools. Call them in every session.

start_session

Call this at the start of every session. Returns the active project context for the current directory plus a compact map of all other projects — one API call, ~100–180 tokens total. Do not call list_context_map + get_context separately; this replaces both.

update_context

Push a context update. Call this whenever: a decision is made, the current task changes, a blocker is found, or meaningful progress happens. Don't wait until the end of the session — updates are cheap and keep the brief every new session reads current.

project_id: "proj-abc123"
summary: "Switched auth from JWT to session tokens — JWT had XSS risk via localStorage. Now using Redis-backed sessions."

get_context

Get project context by section. Defaults to [task, status] (~30 tokens). Pass sections=["all"] for everything.

project_id: "proj-abc123"
sections: ["task", "decisions", "blocking"]

import_local_context

Import context from CLAUDE.md, AGENTS.md, or .cursorrules in the current directory. Call without confirmed: true first — it shows a free preview of what would be imported. Then call again with confirmed: true to commit.

complete_setup

One-call setup fallback for brittle hosts: checks auth status, applies local setup for a surface, and runs import_local_context preview + confirmation if local files are found.

Example:

complete_setup
{
  "surface": "cursor"
}

cleanup_context

Clean up task state at handoff or finish time. Use this to mark the active task complete and clear open-task command history so the next agent sees clean state.

When the task is clearly done and there are no unresolved questions, call this automatically with complete_task=true (no extra confirmation loop).

cleanup_context
{
  "complete_task": true
}

search_context

Search across all projects. Examples: "decisions about authentication", "projects using PostgreSQL", "what's blocking the billing work".

list_projects

List all projects with IDs and last-updated timestamps. Use this when you explicitly need a project index. For normal startup, prefer start_session.

create_project

Create a new project when starting something that has no existing project entry.

Workspace knowledge tools

get_workspace_overview

Use mode=startup at the start of a session for a compact orientation brief. Use mode=overview when the user asks "what am I working on?" or wants a broader picture.

get_workspace_entities

Drill into typed workspace knowledge: decisions, tools, environments, capabilities. Filter by types, query, status, or project_id.

get_project_map

Return durable file-level project memory: hot paths, entrypoints, named surfaces, and debugging notes. Use this before repo-wide search when the path may already be known.

find_known_paths

Search DeerDawn’s durable path memory for queries like "auth modal" or "signup route" before using repo search.

get_next_best_context

Get ranked suggestions for what context to fetch next, given the current tool and working directory.

upsert_workspace_entities

Create or update durable workspace knowledge — tools, environments, architectural decisions, or capabilities that apply across multiple projects.

record_hot_paths

Write discovered file or folder paths back into DeerDawn so future sessions can orient without re-discovering them.

record_debug_finding

Store concise durable debugging findings, optionally tied to specific paths.

How it works

A fresh AI session knows nothing about your project — it would start cold. DeerDawn hands it the brief instead.

You work in Claude Code, Cursor, or ChatGPT
  → DeerDawn captures the session (via MCP, browser extension, or desktop app)
  → Extraction pipeline distills what changed (task, decisions, blockers, stack) into the brief
  → The brief is stored per-project in your workspace and kept current
  → Next session would start cold — instead start_session hands it the brief in one call
  → Every new session opens already briefed, never from a blank slate

The brief is stored per-project. Critical decisions are flagged and always surface first, regardless of token budget. If sections are trimmed, you'll see exactly what was dropped and how to retrieve it.

Verify installation

After saving your config and restarting the agent, call start_session first:

start_session

If it returns your active project context, DeerDawn is already connected — you're done, skip the rest. (If you connected through the claude.ai connector rather than this standalone server, this is the normal path: apply_setup and import_local_context won't exist on that build and aren't needed — context loads automatically.)

If start_session reports you're not authenticated, complete sign-in and seed context:

get_auth_status
import_local_context
import_local_context {"confirmed":true}
start_session
cleanup_context {"complete_task":true}

If your host prefixes tool names, use deerdawn-get_auth_status and deerdawn-import_local_context instead.

If your host is flaky during setup, run complete_setup {"surface":"claude_code"} as a one-call fallback — it checks auth, applies surface setup automatically, and imports local context in a single call. apply_setup is called internally and does not need to be run manually.

You should get back your active project context (or a prompt to import local context if it's a new workspace). If you get an error instead:

• Confirm DEERDAWN_API_KEY starts with dd_
• Fully restart the agent (not just reload)
• Check MCP logs: ~/Library/Logs/Claude/mcp*.log (Claude Desktop) or equivalent

Troubleshooting

Server won't start

1. Verify DEERDAWN_API_KEY starts with dd_
2. Fully restart your editor after saving the config
3. Check MCP 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

start_session returns no projects Call import_local_context (without confirmed: true first) to seed context from a CLAUDE.md or AGENTS.md in your current directory.

Authentication error API key must start with dd_. If you're using the device flow, call get_auth_status and open the returned URL in your browser.

Slow responses The extraction pipeline runs on first import. Subsequent start_session calls are fast (cached context lookup, no LLM call unless something changed).

Governance tools (separate sub-product)

DeerDawn also includes a policy decision engine for AI agent guardrails. These tools are available in the same server but serve a different use case:

evaluate_decision, get_decision, list_decisions, get_decision_stats, list_policies, create_policy, update_policy, delete_policy, get_policy_versions, create_policy_from_template, list_escalations, get_escalation, resolve_escalation, get_organization_settings, update_organization_settings

See governance.deerdawn.com for documentation on the policy engine.

Development

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

License

MIT