Deerdawn

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.

About this repository. DeerDawn is a hosted service. This repo holds the

public install guide, the server.json manifest published to the MCP registry,

and a Dockerfile that launches the published npm package. The server itself

ships from npm as @deerdawn/mcp-server;

its source is not open. Issues and questions are welcome here.

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

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.

---

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, Deer