MCP server

scoutjobs mcp exposes every CLI command as an MCP tool over stdio, and scoutjobs serve over HTTP on /mcp, for Claude Desktop, Codex, Cursor, n8n and any other MCP client.

.md

scoutjobs mcp is a Model Context Protocol server on stdin and stdout: newline-delimited JSON-RPC 2.0, no network port, no token. Every tool is a scoutjobs command run in-process with --json, so an MCP client gets the same rows the skills get. The server starts in a few milliseconds and keeps no state of its own; the data stays in ~/.scoutjobs.

Tools

Tool CLI command

Tool	CLI command
`brief`, `stats`, `funnel`, `doctor`	`scoutjobs brief --compact`, `scoutjobs stats --json`, `scoutjobs stats --funnel --json`, `scoutjobs doctor --json`
`daily`	`scoutjobs daily --json`: the daily chores, nothing sent
`job_list`, `job_show`, `job_add`, `job_set`, `job_fit`, `job_check`, `job_review`, `job_skip`	`scoutjobs job …`
`search`	`scoutjobs search --json --compact`, ranked by the profile match; `location` and `hide_mismatches` narrow it, `add: true` tracks the matches
`cv_files`, `cv_log`, `cv_list`, `cv_export`	`scoutjobs cv …`
`email_draft`, `email_show`, `email_sync`	`scoutjobs email …`; `email_send` and `email_test` are not exposed
`decision_log`, `decision_summary`	`scoutjobs decision …`
`pref_list`, `pref_set`, `pref_rm`	`scoutjobs pref …`
`interview_list`, `interview_add`, `interview_set`	`scoutjobs interview …`
`session_log`, `session_list`	`scoutjobs session …`
`learn_list`, `learn_add`, `learn_set`	`scoutjobs learn …`
`run`	any argument list, e.g. `["job","list","--json"]`; `email send`, `email test`, `serve` and `mcp` are refused

brief, stats, funnel, doctor

scoutjobs brief --compact, scoutjobs stats --json, scoutjobs stats --funnel --json, scoutjobs doctor --json

daily

scoutjobs daily --json: the daily chores, nothing sent

job_list, job_show, job_add, job_set, job_fit, job_check, job_review, job_skip

scoutjobs job …

search

scoutjobs search --json --compact, ranked by the profile match; location and hide_mismatches narrow it, add: true tracks the matches

cv_files, cv_log, cv_list, cv_export

scoutjobs cv …

email_draft, email_show, email_sync

scoutjobs email …; email_send and email_test are not exposed

decision_log, decision_summary

scoutjobs decision …

pref_list, pref_set, pref_rm

scoutjobs pref …

interview_list, interview_add, interview_set

scoutjobs interview …

session_log, session_list

scoutjobs session …

learn_list, learn_add, learn_set

scoutjobs learn …

run

any argument list, e.g. ["job","list","--json"]; email send, email test, serve and mcp are refused

Sending e-mail is not on the server by design: the agent drafts, the user runs scoutjobs email send <id> --yes in a terminal. See Apply by e-mail.

Clients

Claude Code picks the server up from the repository’s .mcp.json; for any project, add it by hand:

$ claude mcp add scoutjobs -- scoutjobs mcp

Claude Desktop, claude_desktop_config.json:

{"mcpServers": {"scoutjobs": {"command": "scoutjobs", "args": ["mcp"]}}}

Codex, ~/.codex/config.toml:

[mcp_servers.scoutjobs]
command = "scoutjobs"
args = ["mcp"]

Cursor, .cursor/mcp.json in the project or ~/.cursor/mcp.json:

{"mcpServers": {"scoutjobs": {"command": "scoutjobs", "args": ["mcp"]}}}

scoutjobs must be on the PATH the client starts with. GUI apps on macOS do not read your shell profile, so give the full path (/opt/homebrew/bin/scoutjobs or $HOME/go/bin/scoutjobs) when the client reports "command not found".

Over HTTP

scoutjobs serve also answers MCP on POST /mcp, the Streamable HTTP transport, for clients that cannot start a local process: n8n’s MCP Client Tool node, cloud agents, a claude.ai custom connector behind a tunnel. The tools are the same as on stdio.

api_token in config.yaml is required; without it /mcp answers 403. Send it as Authorization: Bearer <api_token>, or as ?token=<api_token> for a client that cannot set headers (the token then shows up in logs).
A request with an Origin header other than the server’s own address is refused, so a web page in your browser cannot call the tools.
Every request gets one JSON response; there is no event stream, so GET /mcp answers 405. Notifications get 202.
Tool calls run one at a time, in the order they arrive.

$ curl -s -X POST http://127.0.0.1:7070/mcp -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"brief","arguments":{}}}'

The dashboard binds to 127.0.0.1 by default. Expose /mcp beyond the machine only through a tunnel or reverse proxy with TLS, and treat api_token as a password: anyone holding it can change your pipeline.

Protocol

$ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"brief","arguments":{}}}' | scoutjobs mcp

Supported methods: initialize, notifications/initialized, ping, tools/list, tools/call. Resources and prompts are not implemented; the skills already carry the prompts. Tool failures come back as a result with isError: true and the CLI error text, so the model can correct its call.

Edit this page Last updated October 12, 2026