northstar-agent-bridge

Reference MCP bridge implementation for Northstar.

It exposes the endpoints Northstar calls:

• GET /health
• POST /tools/run_story
• POST /tools/report_status
• POST /tools/submit_result

Install

pip install northstar-agent-bridge

Or for local dev in this repo:

pip install -e packages/northstar-agent-bridge

Initialize backend MCP config (recommended):

python -m northstar_agent_bridge init --backend-env backend/.env --runner-mode codex

Store PAT once:

python -m northstar_agent_bridge login --api-key <ns_pat_...>

Configuration

Set these env vars:

MCP_PROVIDER_NAME=codex-local-bridge
MCP_BRIDGE_HOST=127.0.0.1
MCP_BRIDGE_PORT=8787

# Optional runtime mode
MCP_RUNNER_MODE=mock
MCP_MOCK_DELAY_SECONDS=8
MCP_RUNNER_CMD=codex
MCP_CODEX_CMD=codex exec --json --full-auto --skip-git-repo-check -
MCP_RUNNER_TIMEOUT_SECONDS=1800
MCP_BACKEND_BASE_URL=http://127.0.0.1:8000
MCP_PAT_VALIDATE_URL=http://127.0.0.1:8000/api/v1/spec-cli/auth/pat/validate
MCP_PAT_CACHE_TTL_SECONDS=300

MCP_RUNNER_MODE:

• mock: in-memory simulated completion
• command: executes MCP_RUNNER_CMD with task_markdown piped to stdin
• codex: built-in codex runner using MCP_CODEX_CMD (or MCP_RUNNER_CMD, default codex exec --json --full-auto --skip-git-repo-check -)

Run

northstar-agent-bridge

or:

python -m northstar_agent_bridge

This now starts the bridge in the background (daemon mode) and returns your shell immediately.

Useful commands:

northstar-agent-bridge status   # check daemon state
northstar-agent-bridge stop     # stop daemon
northstar-agent-bridge serve    # run foreground (debug mode)