> For the complete documentation index, see [llms.txt](https://pharaoh.so/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pharaoh.so/docs/connect/headless.md).

# Headless and SSH

Connect Pharaoh's MCP server on a headless machine or over SSH. Sign in with a device code in a browser on another device, with or without Claude Code.

Run `npx @pharaoh-so/mcp` where the agent runs. It signs you in and adds Pharaoh to Claude Code, so it needs the Claude Code CLI (`claude`) on your PATH. If it cannot open a browser, follow the authorization URL and code it displays in a browser on another device. Complete GitHub authorization there, then return to the agent.

Without the `claude` CLI, run `npx @pharaoh-so/mcp --install-skills`. It sets up OpenClaw (MCP server and skills) and adds the review skill for Codex. Any agent other than OpenClaw also needs a stdio MCP server that runs `npx @pharaoh-so/mcp@<version>` (`npm view @pharaoh-so/mcp version` prints the latest). The agent's first Pharaoh tool call returns an authorization URL and a code: open the URL on any device, complete GitHub authorization, then re-run the tool.

Do not paste access tokens into prompts or commit them to repository configuration. A custom MCP integration must support Pharaoh's authentication flow; a URL alone does not grant repository access.

## Over SSH

Run the command in the SSH session on the remote machine, not on your laptop. The agent reads its MCP configuration and Pharaoh's credentials on the machine where it runs. The authorization page works from any browser, so you can approve the code on your laptop or phone while the remote session waits.

## Where credentials live

After authorization, credentials are saved in `~/.pharaoh/credentials.json` on the agent's machine, readable only by your user. Access tokens last 7 days and renew on their own, so a long-running server does not need a new sign-in each week.

## Verify the connection

With Claude Code, run `claude mcp list` and check that `pharaoh` is listed and connected. In any agent, ask: “Use Pharaoh's get\_codebase\_map for owner/repo and show the last refreshed time.” On the [setup page](https://mcp.pharaoh.so/setup), **Connect your AI client** then shows the time of that question.

## Common errors

* **“Device code expired”**: codes last 5 minutes. Run the command or tool again for a new URL and code.
* **Setup stops before sign-in**: the `claude` CLI is not on your PATH. Nothing is written and saved credentials stay. Install the CLI, or use `--install-skills`.
* **Signed in as the wrong GitHub account**: run `npx @pharaoh-so/mcp --logout` to clear the credentials and Claude Code configuration, then set up again.

[Connection checks](/docs/use-pharaoh/troubleshooting.md)