Headless / SSH / CI

Connect Pharaoh in environments without a browser: VPS, containers, SSH sessions, CI pipelines.

Prerequisite: Install the GitHub App first.

Setup

Run the device flow CLI:

npx @pharaoh-so/mcp

1. The CLI prints a URL and a one-time code

2. Open the URL on any device with a browser

3. Enter the code and authorize with GitHub

4. The MCP connection starts via stdio

Requires Node.js 18+.

Configure with your AI tool

For any tool that supports stdio MCP transport, add this to its MCP config:

{
  "mcpServers": {
    "pharaoh": {
      "command": "npx",
      "args": ["@pharaoh-so/mcp"]
    }
  }
}

For Claude Code specifically:

npx @pharaoh-so/mcp

The device flow runs on first connection. After authorization, the token is cached locally.

Verify

Ask your AI tool:

What modules does this codebase have?

It should call get_codebase_map and return a module breakdown with file counts, function counts, and dependency relationships.

What happens automatically

• Your AI tool calls Pharaoh tools before making architectural decisions - checking for duplicate functions, understanding callers, mapping module boundaries

• Every push to your default branch refreshes the graph within minutes

• No config files or per-repo setup needed after the initial install

• Pharaoh tools return structured data in minimal tokens so the AI has room to reason

Troubleshooting

npx fails or command not found: Ensure Node.js 18+ is installed. Run node --version to check. Install from nodejs.org or via your package manager.

Device code expired: Codes expire after 15 minutes. Run npx @pharaoh-so/mcp again to get a new code.

Connection works once then fails on restart: The cached token may have expired. Re-run the device flow to get a fresh token.

"No repos found" after authorization: The GitHub App must be installed on the correct org or account. Go to github.com/apps/pharaoh-so/installations/new and verify the installation.

Firewall blocks outbound connections: Pharaoh requires HTTPS access to mcp.pharaoh.so (port 443) and github.com (port 443) for the OAuth flow.