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
| 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. |
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.
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:
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
npm run dev
npm test
npm run lint
License
MIT