@dreamworkhq/mcp

@dreamworkhq/mcp

MCP server for Dreamwork — the job-search intelligence layer for AI agents. Gives any MCP client (Claude Desktop, Cursor, the MCP Inspector, etc.) the long-term context to find roles, rank them, tailor applications, auto-apply, and track outcomes for a candidate over time.

This server is a thin gateway: it calls the Dreamwork API over HTTPS and holds no database access of its own. Transport is stdio — stdout carries only JSON-RPC frames.

Install

No install step is required — MCP clients run it on demand with npx. The examples below use npx -y @dreamworkhq/mcp.

Configure

Claude Desktop

Add an entry to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "dreamwork": {
      "command": "npx",
      "args": ["-y", "@dreamworkhq/mcp"],
      "env": {
        "DREAMWORK_API_KEY": "sk_..."
      }
    }
  }
}

Restart Claude Desktop after editing. Put credentials in the env block — don't wrap command in a shell or an env-loader (dotenvx run -- …, etc.): on a stdio server any banner such a wrapper prints to stdout will corrupt the JSON-RPC stream and hang tool calls.

Cursor and other clients

Any stdio MCP client works. Cursor uses the same config shown above — point the command at npx -y @dreamworkhq/mcp and pass DREAMWORK_API_KEY in the environment. To sanity-check with the Inspector:

DREAMWORK_API_KEY=sk_... npx @modelcontextprotocol/inspector npx -y @dreamworkhq/mcp

This package speaks stdio only. Dreamwork does not currently host a remote (streamable-HTTP) MCP endpoint, and claude.ai / Claude Desktop custom connectors are not yet supported — the connector dialog authenticates via OAuth and cannot accept sk_ agent keys. On Claude Desktop, use the claude_desktop_config.json entry above instead.

Authentication

Generate an agent key from your Dreamwork profile: sign in at dreamworkhq.com, open your profile → Agent key section (or use the Get your agent key button on the Agents page), then set it as DREAMWORK_API_KEY (format sk_...).

Guest mode: with no key set, the server still starts and exposes the public, read-only tools (browse_listings, get_listing, get_platform_context). Account tools return a short "Login required" message until a key is provided.

Environment variables

Variable	Required	Default	Purpose
DREAMWORK_API_KEY	For account tools	—	Agent API key (sk_...). Unlocks pipeline, resume, apply, outreach, profile, interviews.
DREAMWORK_API_URL	No	https://api.dreamworkhq.com	Override the API endpoint (local dev / self-host).

JOBLESS_API_TOKEN and JOBLESS_API_URL are still accepted as backward-compatible aliases for DREAMWORK_API_KEY and DREAMWORK_API_URL; prefer the DREAMWORK_ names for new configs.

Telemetry

To measure usage, the server generates an anonymous random install id (a UUID) on first run and stores it under your OS state directory ($XDG_STATE_HOME/dreamwork/install-id, ~/.local/state/dreamwork/install-id on Linux/macOS, or %LOCALAPPDATA%\dreamwork\install-id on Windows). It is a random value only — never derived from your hostname, username, or any machine attribute — used to count unique installs of guest (unauthenticated) usage. It is written at runtime on your machine, never at build or publish time.

Opt out by setting either environment variable:

• DREAMWORK_TELEMETRY=0 (also false/no/off)
• DO_NOT_TRACK=1 (the standard opt-out; also true/yes/on)

With telemetry disabled, no install id is generated, read, or sent.

Tools

The typical flow: browse the public index → save roles to the pipeline → tailor materials → auto-apply → track replies, interviews, and escalations.

Public (no key): get_platform_context, browse_listings, get_listing

• browse_listings / get_listing search Dreamwork's public job index (thousands of roles from Greenhouse, Lever, Ashby, Workday, and more).

Pipeline & applications: search_jobs, get_job, import_job, add_jobs, apply_to_job, skip_job, list_applications, add_listing_to_pipeline, get_stats

• get_stats aggregates the signed-in candidate's own pipeline, so it needs a key like the rest of the pipeline tools.

• Despite the name, search_jobs lists jobs already in the user's pipeline (use browse_listings to search the public index).

• apply_to_job runs the full auto-apply agent: it generates a cover letter and tailored resume, launches a browser, fills the application form, solves CAPTCHAs where possible, and submits (the job must have a URL).

Resume & materials: upload_resume, generate_resume, get_generated_resumes

Outreach & contacts: add_contact, list_contacts, generate_outreach, send_outreach

Profile, interviews & escalations: get_profile, update_profile, list_interviews, list_escalations, resolve_escalation

Call get_platform_context first — it describes what Dreamwork can do so the agent picks the right workflow.

Troubleshooting

• Tool calls hang / time out, but the handshake succeeds. Something is writing non-JSON-RPC bytes to stdout. Make sure command isn't wrapped in an env-loader or shell that prints a banner, and update to the latest version (npx -y @dreamworkhq/mcp@latest; clear the npx cache with rm -rf ~/.npm/_npx if an old build is cached). stdout must carry only protocol frames — all server logging goes to stderr.
• Every account tool says "login required". DREAMWORK_API_KEY isn't reaching the process. Confirm it's in the env block of your client config.

Development

pnpm --filter @dreamworkhq/mcp check   # typecheck
pnpm --filter @dreamworkhq/mcp build   # emit dist/
pnpm --filter @dreamworkhq/mcp test    # unit tests

The stdio entrypoint is src/stdio.ts; tool definitions live in src/mcp.ts; the HTTP API client is src/client.ts.

The server reads configuration from the process environment only — it does not load a .env file. For local development export the vars in your shell (e.g. DREAMWORK_API_URL=http://127.0.0.1:3000 pnpm --filter @dreamworkhq/mcp stdio).

Package-boundary decisions, tool-registration conventions (registerDreamworkTool), error/versioning rules, and deferred review triggers are recorded in ARCHITECTURE.md. The tool catalog below is drift-checked against the registered tools by test/tool-catalog.test.ts.

License

MIT