so.pharaohPublished by pharaoh.soOfficial publisherv1.0.286Updated Nov 7, 2026
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Pharaoh gives coding agents a queryable knowledge graph of a mapped repository, so they can answer architecture, dependency and impact questions without…
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/so.pharaoh%2Fpharaoh/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.
{
"mcpServers": {
"pharaoh": {
"type": "http",
"url": "https://mcp.pharaoh.so/mcp"
}
}
}[npm version] [license] [node] [pharaoh MCP server]
MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for coding agents.
Pharaoh gives coding agents such as Claude Code, Cursor, Codex and OpenClaw a complete architectural map of your codebase: every function, dependency, module, and connection. Instead of reading files one at a time, your agent queries the knowledge graph and gets instant answers about blast radius, unused code, dependency chains, and more.
This package enables Claude Code to connect to Pharaoh in headless environments (VPS, SSH, containers, CI) where a browser isn't available for OAuth. It acts as a stdio-to-SSE proxy, presenting itself as a local MCP server while relaying all communication to the remote Pharaoh server.
Run the proxy directly to trigger the device authorization flow:
This displays a device code and a URL. Open the URL on any device (phone, laptop, tablet) and enter the code to authorize. Credentials are saved to ~/.pharaoh/credentials.json and remain valid for 7 days, with automatic re-authorization when they expire.
Verify the connection:
You should see pharaoh listed as a stdio server.
If you previously added Pharaoh as an SSE server, remove it first:
The proxy implements the Model Context Protocol (MCP) specification:
Authentication uses RFC 8628 (OAuth 2.0 Device Authorization Grant) — no browser is needed on the machine running Claude Code.
Once connected, Pharaoh provides these MCP tools:
Use --inspect to dump the full tool manifest as JSON (useful for MCP registry validation and debugging):
This outputs the complete list of tools with their schemas and exits immediately, without connecting to the server.
Credentials are stored at ~/.pharaoh/credentials.json with 0600 permissions (owner-read/write only). The file contains:
To clear credentials:
For self-hosted Pharaoh instances or development, register manually, pinned to a version (npx @pharaoh-so/mcp --version prints the one you have):
0600 — owner-read/write only)~/.claude/CLAUDE.md holds the line setup suggests, mentions Pharaoh another way, doesn't, or is missing, and whether setup's block is still in it. In Claude Code started at a git repo's root, it does the same for that project's CLAUDE.md, CLAUDE.local.md, .claude/CLAUDE.md and AGENTS.md. Only these values are sent, never the files' text.~/.claude/settings.json. Nothing else about your machine is sent.npx @pharaoh-so/mcp in a terminal is the interactive setup. Every later proxy start (Claude Code launching the server) repeats the plugin, skill and command steps so a new version takes effect, and nothing else.
Versions 0.3.46 and earlier wrote one rule, mcp__pharaoh, on every proxy start. That prefix auto-approved every Pharaoh tool, including account deletion and pharaoh_admin, so a prompt injection could run them without a human prompt. The next interactive setup replaces that rule with the list above; account deletion, pharaoh_admin and any tool not listed prompt before they run. To take the blanket rule out by hand, delete mcp__pharaoh from permissions.allow.
Every registration the setup writes runs the exact version that wrote it (npx @pharaoh-so/mcp@<version>). A new release on npm changes nothing on your machine until you upgrade:
This signs you in again, rewrites the registration with the new version and refreshes the plugin. The interactive setup asks the npm registry for the newest version and prints a one-line hint when there is one; proxy starts never check.
If you discover a security vulnerability, please report it responsibly by emailing [email protected]. Do not open a public issue.
The Pharaoh server may be temporarily unavailable. Check status.pharaoh.so or try again in a few minutes.
Re-authenticate by running the proxy directly:
Or clear credentials and start fresh:
claude mcp listMake sure you added it with the correct command:
Note the -- separator between pharaoh and npx.
The first run after installation may take a moment as npm downloads the package. Subsequent runs use the cached version. To pre-install globally:
Pharaoh parses your repositories using tree-sitter and maps structural metadata into a Neo4j knowledge graph. The graph contains:
No source code is stored — only structural metadata. When an agent queries Pharaoh, it gets architectural facts in minimal tokens, not raw code dumps. This means your agent can understand your entire codebase architecture without consuming its context window reading files one by one.
Contributions are welcome. Please open an issue first to discuss what you'd like to change.
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)MIT -- 2407066 Alberta Inc.
Source: README.md at commit be82947
Codebase Map
A repo's architecture in one call. CALL THIS WHEN: • Orienting in a repo or locating a module • The mapped repo name is unknown RETURNS: Modules and LOC, dependencies and cycles, hot files (5), endpoints (50), entry points (30), exact clones and high-risk functions without direct test links.
reporequiredinclude_healthinclude_metricsCodebase Recon
Several Pharaoh queries in one call, run in parallel: codebase map, module profiles, function searches, blast radius and module dependency paths. CALL THIS WHEN: • Planning a change, reviewing a PR or assessing architecture, when the modules and functions to check are known RETURNS: Each requested section in one response, as the single-purpose tools return it. Per call: up to 5 modules, 3 searches, 3 blast radius targets, 3 dependency pairs.
reporequiredmodulesfunctionsinclude_mapblast_radiusdependenciesModule Context
One module's profile: what it contains, depends on and is called by. CALL THIS WHEN: • Changing code in a module, or planning a change to it • Finding what a module exports, depends on, or which code calls into it RETURNS: Files, LOC, exported signatures with complexity, imports in and out, DB tables, endpoints, cron jobs, env vars, and callers in other modules, grouped by module.
reporequiredmodulerequiredBlast Radius
What a change to a function, file or module reaches. CALL THIS WHEN: • Changing a signature, refactoring or deleting code • Finding a change's callers or entry points RETURNS: Detected production callers (depth 1 is direct only). Hosted adds risk, endpoints, cron jobs and DB operations. Verified worktrees report saved-file callers and coverage.
reporequireddepthscopeentityrequiredentity_typerequiredlocal_contextSearch Functions
Find functions by name or concept across the whole codebase. CALL THIS WHEN: • Checking whether a function, helper or utility already exists • Finding where something is implemented (e.g. "retry", "validate", "notify") RETURNS: Matching functions with file path, line range, module, signature, export status and complexity. Matches name parts (camelCase, snake_case) and file paths, not comments; test code ranks last. SCREAMING_SNAKE queries, and queries no function matches, return matching constants with up to 80 characters of each value.
filereporequiredlimitqueryrequiredmoduleoffsetexported_onlyUnused Code
Find code nothing runs: functions no production entry point (endpoint, CLI command, cron job, event handler, worker, entry file) reaches. CALL THIS WHEN: • Cleaning up a module or deleting a function • Confirming new code is reached from an entry point RETURNS: Reachability through the call graph, not text references. • Dead: unreached, named in no other file, and no import of its file could reach it. • Possibly unused: unreached, but named in other files (string dispatch, dynamic loading) or an import of its file could reach it. Listed with the files that name it. • Used only by tests: exported functions and class methods only test files reference. With `functions`: each one's status, and the call path from an entry point when it's reachable.
reporequiredmodulefunctionsSetup
Pharaoh's connection and setup status for the repo you're working in. Writes no files. CALL THIS WHEN: • The user asks to set up Pharaoh, or to check its setup • Pharaoh was just connected and the user asks what to try first RETURNS: Connection, mapped-repo and access status, a Codebase Health link, optional first-use choices, and the Pharaoh-first instructions line only when needed.
reporequiredAccount Status
Your Pharaoh plan and mapped repos in each workspace. Changes nothing. CALL THIS WHEN: • Checking which plan a workspace is on • A tool says the plan doesn't include it, or a repo isn't mapped • Finding the setup page or the billing page RETURNS: Each workspace you can access with its plan and tracked-repo count, whether its repos are mapped on every push, the setup page, and the billing page when a workspace has a billing account.
actionRefresh Repo
Re-map a repo now. Every repo is mapped during the trial and on Pro, and re-maps on every push. • refresh_repo { repo, full? }: queue a re-map of one repo. • set_free_repo { repo }: retired; it changes nothing, since there is no live repo to choose. CALL THIS WHEN: • A repo's graph looks out of date, or needs a full rebuild RETURNS: The queued job.
fullreporequiredactionrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
npx @pharaoh-so/mcpnpx @pharaoh-so/mcpclaude mcp listclaude mcp remove pharaohnpx @pharaoh-so/mcpClaude Code ← stdio → @pharaoh-so/mcp ← SSE/HTTP → mcp.pharaoh.sonpx @pharaoh-so/mcp --inspectUsage: pharaoh-mcp [options]
Options: --server <url> Pharaoh server URL (default: https://mcp.pharaoh.so) --logout Clear stored credentials and exit --inspect Output tool manifest as JSON and exit --help Show help --version Show version numbernpx @pharaoh-so/mcp --logoutclaude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version> --server https://your-pharaoh-instance.comnpx @pharaoh-so/mcp@latestnpx @pharaoh-so/mcpnpx @pharaoh-so/mcp --logoutnpx @pharaoh-so/mcpnpx @pharaoh-so/mcpnpm install -g @pharaoh-so/mcpclaude mcp add --scope user pharaoh -- pharaoh-mcp