The button installs the server. Replace YOUR_API_KEY in Cursor with your PlanetGraph key to complete authentication. Alternatively, you can merge this configuration into your personal ~/.cursor/mcp.json.
Verify by calling planetgraph_me, then discover DataSets using the recommended prompt below.
VS Code setup
Approve installation, then paste your PlanetGraph key when VS Code prompts. This setup is for local VS Code sessions. For Copilot harness sessions, select "Add to GitHub Copilot" above. Manual fallback: MCP: Open User Configuration.
Copilot sessions in VS Code: merge this into $COPILOT_HOME/mcp-config.json, or ~/.copilot/mcp-config.json when COPILOT_HOME is unset. Interactive VS Code input variables are not supported here. Supply PLANETGRAPH_API_KEY in the environment of the connecting application. A variable set in a terminal does not automatically reach an already-running desktop app.
Verify by calling planetgraph_me, then discover DataSets using the recommended prompt below.
Codex setup
Add this table to ~/.codex/config.toml, or merge its fields into an existing planetgraph table; do not duplicate the table. No OAuth login command is needed or supported by PlanetGraph yet. Supply PLANETGRAPH_API_KEY in the environment of the connecting application. A variable set in a terminal does not automatically reach an already-running desktop app.
Verify by calling planetgraph_me, then discover DataSets using the recommended prompt below.
Claude Code setup
Requires the Claude Code CLI. A variable set in a terminal does not automatically reach an already-running desktop app.
macOS / Linux terminal
claude mcp add --transport http --scope user planetgraph "https://api.planetgraph.ai/mcp/" --header "X-API-Key: ${PLANETGRAPH_API_KEY}"
claude mcp get planetgraph
Windows PowerShell
claude mcp add --transport http --scope user planetgraph "https://api.planetgraph.ai/mcp/" --header "X-API-Key: $env:PLANETGRAPH_API_KEY"
claude mcp get planetgraph
Verify by calling planetgraph_me, then discover DataSets using the recommended prompt below.
Claude Desktop / Web setup
Settings > Connectors > Add custom connector: enter the endpoint below. If Request headers is available, choose No sign-in and add required header X-API-Key with your raw key. Header support is limited beta. A shared organization key grants its account access and can spend tokens. Remote connectors cannot reach localhost. Without Request headers, use the Desktop-only proxy below; it does not enable Claude web or Cowork.
Set Headers: Key: "X-API-Key", Value: your PlanetGraph API key.
Verify by calling planetgraph_me, then discover DataSets using the recommended prompt below.
Manual Configuration setup
Choose the format your client actually supports. Direct HTTP is preferred. The local proxy requires Node.js / npx and is only for clients without usable HTTP/header support. Replace placeholders locally; the public manifest never contains your key.
List visible DataSets, describe the relevant DataSet to discover its canonical node and edge types, then use schema discovery for declared Access and Search capabilities. Individual records may differ, so inspect bounded samples when needed.
The Query Engine builds logical steps, executing previews as it plans. Call planetgraph_query_build with request, optional dataset_id, and limit (1-100). While status is building, continue with the returned plan_id as build_id and latest version. When ready, call planetgraph_query_answer with that plan_id and version. Request-only answers use the same engine and advance up to 26 planning transitions before executing or returning the stopped build.
Use planetgraph_query_run_get with run_id to restore saved results without rerunning or charging. For another page, pass next_cursor as cursor to planetgraph_query_answer with the same plan_id, version, and run_id. Generate API guidance with planetgraph_query_api_guide: Markdown sections explain each accepted step, curl calls, output dependencies, API gaps, and client-side workarounds. Guides are cached, unverified guidance, not proof of API parity.
Resolve an anchor ID with Property search (or pass {"$resolve": {"type", "name"}} as a parameter value), validate and run bounded Cypher to find related IDs, then retrieve selected authorized Properties for the result set. planetgraph_query_run accepts timeout_ms (clamped to your account ceiling), page_size/cursor for large results, explain for the execution plan, and mode "async" for long traversals; poll planetgraph_query_run_status with the returned run_id. Responses include projection_watermark so you can tell "not connected" from "not projected yet".
When you want to find similar nodes or edges based on meaning rather than exact text.
4. Tool Reference
Health and identity
Basic connectivity and authenticated user context.
planetgraph_health
Returns service status and MCP metadata.
planetgraph_me
Returns the authenticated PlanetGraph user and account.
Graph inspection
Browse nodes, edges, and type vocabularies.
planetgraph_nodes_list
Lists visible nodes with a flat filters array and filter_mode=AND or OR before pagination. include_properties retains value-access policies; check results_may_be_incomplete for pending indexes.
planetgraph_nodes_get
Fetches one node by ID.
planetgraph_node_types_list
Lists known node types.
planetgraph_edges_list
Lists visible edges with flat Property filters and endpoint restrictions before pagination. filter_mode defaults to AND; include_properties retains value-access policies.
planetgraph_edges_get
Fetches one edge by ID.
planetgraph_edges_for_node
Lists a node’s incoming and outgoing edges.
planetgraph_edge_types_list
Lists known edge types.
planetgraph_schema_describe
Lists declared Access and Search capabilities with Access Policy names and default token prices; individual Properties may override those defaults.
Search and querying
Use logical plans for natural-language questions; explicit Cypher tools remain available for advanced queries.
planetgraph_query_build
Proposes, executes, and validates an incremental logical step. Accepted new steps cost 1 token; required comparison inputs may also be purchased. Supports build_id, version, request_id, and renew_retention.
planetgraph_query_answer
Executes an exact ready plan_id/version, or builds and executes a request through the Query Engine, with automatic policy-checked Property hydration. Required inputs may be purchased; locked final display fields are not automatically purchased.
planetgraph_query_build_get
Retrieves an account-owned, unexpired build by build_id, including the latest version and pause reason, without planning or charging.
planetgraph_query_run_get
Retrieves an account-owned, unexpired run by run_id, including saved results, pagination state, and any cached API guide. Rechecks current Property access without re-execution.
planetgraph_query_api_guide
Generates or retrieves a cached Markdown API guide for a completed run_id using current API documentation. Does not execute calls, buy Properties, or charge query tokens. API gaps remain explicit.
planetgraph_properties_search
Searches text or typed ordered Properties. between requires upper_query. Follow has_more with offset + limit; incomplete-index warnings remain separate from pagination. Matching never purchases values.
planetgraph_properties_get_for_resources
Retrieves selected policy-checked Properties for node or edge IDs returned by Cypher, including effective prices for locked fields.
planetgraph_query_capabilities
Describes the recommended logical Query Engine workflow, billing, result limits, saved runs, and the separate advanced Cypher workflow.
planetgraph_query_validate
Validates a query before execution.
planetgraph_query_run
Runs a supported read-only query and returns structural graph records and IDs.
DataSet catalog
Use the catalog as the first discovery step instead of guessing graph labels or scanning member records.
planetgraph_datasets_list
Lists visible graph-backed DataSets and the canonical types each includes. Pass mine=true to restrict results to DataSets owned by your account.
planetgraph_datasets_describe
Pass dataset_id from planetgraph_datasets_list to describe one visible DataSet, including its node types, edge types, and declared Access and Search capabilities.
5. Query Limits And Search Rules
Queries are read-only
Graph structure is read-only. Questions use tokens from your balance: 1 token per accepted planning step, plus tokens for any required comparison inputs, which also creates access grants. When you sign in from a connected app such as ChatGPT or Claude, one question can use at most 100 tokens; API keys are not capped. Explicit Cypher rejects CREATE, DELETE, MERGE, SET, REMOVE, DROP, CALL, FOREACH, LOAD, and UNWIND.
Cypher is an advanced alternative
Questions that connect multiple records can use bounded multi-hop patterns. Resolve a known entity with Property search first and use its resource ID as the Cypher anchor.
Pause states and retries
Continue automatically only while building. Stop on needs_clarification, paused, unsupported, failed, or budget_exhausted and inspect question/reason before acting. Reuse request_id (a UUID) only when retrying the same request; use a new UUID for each continuation. Stale versions are rejected: retrieve the latest build before resuming. Request-only calls can return building at their transition limit; continue that build rather than starting over.
Retention and private diagnostics
Builds and runs expire after 30 days. Use renew_retention=true when explicitly continuing a saved build to renew its retention. Saved results are account-scoped and recheck current access. Planner and execution diagnostics are superadmin-only. Guides contain credential placeholders, never your API key, and cannot guarantee equivalent API behavior.
Cypher results are structural
Cypher can filter on projected searchable Properties but cannot return raw Property values. Retrieve selected values for matched IDs with properties_get_for_resources.
Direct property lookup often beats Cypher
Discover searchable properties with schema_describe, then use properties_search for direct lookups such as Company.name = Apple or Institution.name contains stanford. Matching is case-insensitive.
Schema describes declarations
Declared Properties and token prices are type-level defaults, not a guarantee that every record has them or uses the same effective policy. Batch retrieval reports each Property’s actual access and price.