Model Context Protocol

Connect agents to PlanetGraph.

These docs are optimized for first success: connect with an API key, prove the client can call the server, then try the handful of workflows that matter most.

Transport

Streamable HTTP

Hosted MCP endpoint for remote clients and automation.

Preferred Auth

X-API-Key

Use API keys for agents. Bearer auth also works when you already have a user token.

First Proof

health -> me -> schema

Confirm connectivity, auth, and the graph shape before you ask for real work.

1. Connect With Auth

Endpoint

https://api.planetgraph.ai/mcp/

Headers

Preferred

X-API-Key: YOUR_API_KEY

Also supported

Authorization: Bearer YOUR_TOKEN

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"
      }
    }
  }
}

2. Make The First Three Calls

Aplanetgraph_health

Confirms the transport is live and the client can reach the server at all.

Bplanetgraph_me

Confirms authentication and shows which PlanetGraph user and account the agent is acting as.

Cplanetgraph_schema_describe

Gives the agent the current graph types before it starts guessing node labels or edge names.

3. Main Workflows

Discover

Understand the graph shape

Use this when the agent needs to learn node types, edge types, and schema details before proposing queries.

planetgraph_schema_describeplanetgraph_node_types_listplanetgraph_edge_types_list

Find records by searchable properties

Use direct property search when you know the property name and need exact, prefix, or contains matching over searchable encrypted fields.

planetgraph_properties_searchplanetgraph_nodes_getplanetgraph_edges_for_node

Query

Validate and run read-only Cypher

Use query validation before execution so the agent stays inside the supported PlanetGraph Cypher subset.

planetgraph_query_capabilitiesplanetgraph_query_validateplanetgraph_query_run

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 basic filters.

planetgraph_nodes_get

Fetches one node by ID.

planetgraph_node_types_list

Lists known node types.

planetgraph_edges_list

Lists visible edges with filters.

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

Describes the graph schema and supported query surface.

Search and querying

Find searchable properties and run supported Cypher safely.

planetgraph_properties_search

Searches the derived property index while enforcing search_scope.

planetgraph_query_capabilities

Describes the supported Cypher subset and limitations.

planetgraph_query_validate

Validates a query before execution.

planetgraph_query_run

Runs a supported read-only query and returns results.

5. Query Limits And Search Rules

Queries are read-only

CREATE, DELETE, MERGE, SET, REMOVE, DROP, CALL, FOREACH, LOAD, and UNWIND are rejected.

Traversal stays single-hop

The supported query engine handles single-node matches and single-hop traversals, not arbitrary graph walks.

Property filters are intentionally narrow

Searchable node properties support =, CONTAINS, and STARTS WITH in supported single-node MATCH queries only.

Direct property lookup often beats Cypher

If the job is “find Company.name = Apple”, use planetgraph_properties_search first and only move to query_run when you need richer graph context.