@deerdawn/mcp-server

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.ai, Claude Desktop, ChatGPT, 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 — hosted server (recommended, no install)

Connect to the hosted MCP endpoint. No API key needed — you sign in with your browser the first time a DeerDawn tool is called.

Claude Code

claude mcp add -s user --transport http deerdawn https://api.deerdawn.com/api/v1/mcp

Every other tool — add a remote MCP server (sometimes called a connector) with this URL:

https://api.deerdawn.com/api/v1/mcp

Tool	Where
Claude.ai	Settings → Connectors → Add custom connector
ChatGPT.com	Settings → Connectors → Add MCP server (choose OAuth)
Cursor	Settings → MCP → Add server, or add a "url" entry in .cursor/mcp.json
VS Code / Copilot	Command palette → MCP: Add Server → HTTP → paste the URL
Windsurf, Gemini, others	Add a custom remote / HTTP MCP server with the URL

Leave any OAuth client fields blank. Click Connect (or restart the tool) and sign in when the DeerDawn tab opens. If your tool connects without prompting for sign-in, the first DeerDawn tool call returns the sign-in URL — open it, sign in once, and retry the call; setup completes automatically.

Then say: "Start a DeerDawn session."

The hosted server exposes 18 core session-memory tools. For repo-file writes, automatic capture hooks, and the full 35-tool set, use the local install below.

Local install (stdio) — optional upgrade

Run the server on your machine via npx -y @deerdawn/mcp-server@latest when you want deeper integration:

• Writes .deerdawn-context.md / .cursorrules into your repo so context loads with no tool call.
• Installs SessionStart / Stop hooks that capture and flush context automatically.
• Exposes the full set of 35 tools (the hosted server exposes 18 core ones).

Sign-in works the same way — browser OAuth by default, no API key required. On first run without credentials, the server starts a device-flow sign-in: the URL is printed to stderr, saved to ~/.deerdawn/pending-auth.json, and returned in-band by the get_auth_status tool (use that in GUI hosts where stderr isn't visible). After you approve in the browser, credentials are saved to ~/.deerdawn/credentials.json and every future session is authenticated.

Prefer non-interactive auth (CI, headless, SSH)? Create a key at app.deerdawn.com → Settings → API Keys (it starts with dd_) and set DEERDAWN_API_KEY in the config's env block — browser sign-in is then skipped entirely.

Claude Code (CLI)

Run the setup command — it registers the server, signs you in, and configures hooks 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 -e DEERDAWN_SURFACE_ID=claude_code -- npx -y @deerdawn/mcp-server@latest

Restart Claude Code after registering. If you haven't signed in yet, call get_auth_status — it returns the 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_URL": "https://api.deerdawn.com"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json (same path on macOS, Linux, and Windows):

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  }
}

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_URL": "https://api.deerdawn.com"
      }
    }
  }
}

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_URL": "https://api.deerdawn.com"
        }
      }
    }
  }
}

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

{
  "mcpServers": [
    {
      "name": "deerdawn",
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  ]
}

Zed

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

{
  "context_servers": {
    "deerdawn": {
      "command": {
        "path": "npx",
        "args": ["-y", "@deerdawn/mcp-server@latest"],
        "env": {
          "DEERDAWN_API_URL": "https://api.deerdawn.com"
        }
      }
    }
  }
}

Codex (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.deerdawn]
command = "npx"
args = ["-y", "@deerdawn/mcp-server@latest"]
startup_timeout_sec = 120

[mcp_servers.deerdawn.env]
DEERDAWN_API_URL = "https://api.deerdawn.com"

To skip browser sign-in in any of these configs, add "DEERDAWN_API_KEY": "dd_your_key_here" to the env block (Codex TOML: DEERDAWN_API_KEY = "dd_your_key_here" under [mcp_servers.deerdawn.env]).

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

All optional. With no env vars at all, the server starts and walks you through browser sign-in.

Variable	Required	Default	Description
DEERDAWN_API_URL	No	https://api.deerdawn.com	API base URL. Only change for self-hosted or staging.
DEERDAWN_SURFACE_ID	No	auto-detected	Which tool this server runs in (claude_code, cursor, codex). Detected from the MCP client when unset; set it explicitly to pin session attribution.
DEERDAWN_API_KEY	No	—	API key (dd_...) for non-interactive auth (CI/headless). Default is browser OAuth sign-in. Get one at app.deerdawn.com → Settings → API Keys.

Session memory tools

The local server exposes 35 tools (the hosted remote exposes 18 core ones). These are the ones to reach for 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 hosted remote / claude.ai connector rather than the local 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:

• Call get_auth_status and finish browser sign-in via the returned URL (if you set DEERDAWN_API_KEY instead, confirm it starts with dd_)
• Fully restart the agent (not just reload)
• Check MCP logs: ~/Library/Logs/Claude/mcp*.log (Claude Desktop) or equivalent

Troubleshooting

DeerDawn tools don't appear in your agent The server itself starts with zero env vars — a missing API key never prevents startup. If no DeerDawn tools show up:

• Fully restart your editor after saving the config (not just reload)
• 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

Authentication error / not signed in Call get_auth_status — it returns a browser sign-in URL. Open it, approve, then retry the tool call; setup completes automatically. If you set DEERDAWN_API_KEY, it must start with dd_.

Sign-in reports a rate limit (HTTP 429) This happens after several quick restarts during setup. Wait a minute before retrying — re-running setup immediately will keep hitting the limit.

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.

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

Development

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

License

MIT