Client Configuration
If your MCP client accepts hosted streamable HTTP servers directly (e.g. Cursor), configure it with the endpoint and header below. Exact field names vary by client.
{
"server": {
"transport": "streamable-http",
"url": "https://api.planetgraph.ai/mcp/",
"headers": {
"X-API-Key": "YOUR_API_KEY"
}
}
}Client Configuration (non-hosted)
If your MCP client does NOT accept hosted streamable HTTP servers directly (e.g. Claude Desktop), use npx as a proxy. Exact field names vary by client.
{
"mcpServers": {
"planetgraph": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.planetgraph.ai/mcp/",
"--header",
"X-API-Key:${PLANETGRAPH_API_KEY}"
],
"env": {
"PLANETGRAPH_API_KEY": "YOUR_API_KEY"
}
}
}
}Discover
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.
Basic Search
When you know the property name and want exact, prefix, or contains matching.
Natural-language Answer
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.
Saved Results
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.
Advanced Query
Resolve an anchor ID with Property search, validate and run bounded Cypher to find related IDs, then retrieve selected authorized Properties for the result set.
Semantic Search
When you want to find similar nodes or edges based on meaning rather than exact text.
Basic connectivity and authenticated user context.
planetgraph_healthReturns service status and MCP metadata.
planetgraph_meReturns the authenticated PlanetGraph user and account.
Browse nodes, edges, and type vocabularies.
planetgraph_nodes_listLists 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_getFetches one node by ID.
planetgraph_node_types_listLists known node types.
planetgraph_edges_listLists visible edges with flat Property filters and endpoint restrictions before pagination. filter_mode defaults to AND; include_properties retains value-access policies.
planetgraph_edges_getFetches one edge by ID.
planetgraph_edges_for_nodeLists a node’s incoming and outgoing edges.
planetgraph_edge_types_listLists known edge types.
planetgraph_schema_describeLists declared Access and Search capabilities with Access Policy names and default token prices; individual Properties may override those defaults.
Use logical plans for natural-language questions; explicit Cypher tools remain available for advanced queries.
planetgraph_query_buildProposes, 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_answerExecutes 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_getRetrieves an account-owned, unexpired build by build_id, including the latest version and pause reason, without planning or charging.
planetgraph_query_run_getRetrieves 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_guideGenerates 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_searchSearches 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_resourcesRetrieves selected policy-checked Properties for node or edge IDs returned by Cypher, including effective prices for locked fields.
planetgraph_query_capabilitiesDescribes the recommended logical Query Engine workflow, billing, result limits, saved runs, and the separate advanced Cypher workflow.
planetgraph_query_validateValidates a query before execution.
planetgraph_query_runRuns a supported read-only query and returns structural graph records and IDs.
Use the catalog as the first discovery step instead of guessing graph labels or scanning member records.
planetgraph_datasets_listLists visible graph-backed DataSets and the canonical types each includes. Pass mine=true to restrict results to DataSets owned by your account.
planetgraph_datasets_describePass dataset_id from planetgraph_datasets_list to describe one visible DataSet, including its node types, edge types, and declared Access and Search capabilities.
Graph structure is read-only. Planning and required-input purchases can debit tokens and create access grants; confirm spending intent before building or running a natural-language request. Explicit Cypher rejects CREATE, DELETE, MERGE, SET, REMOVE, DROP, CALL, FOREACH, LOAD, and UNWIND.
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.
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.
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 can filter on projected searchable Properties but cannot return raw Property values. Retrieve selected values for matched IDs with properties_get_for_resources.
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.
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.