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

A planetgraph_health

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

B planetgraph_me

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

C planetgraph_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_describe
• planetgraph_node_types_list
• planetgraph_edge_types_list

Search

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_search
• planetgraph_nodes_get
• planetgraph_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_capabilities
• planetgraph_query_validate
• planetgraph_query_run

4. Tool Reference

Health and identity

Basic connectivity and authenticated user context.

• planetgraph_health
• planetgraph_me

Graph inspection

Browse nodes, edges, and type vocabularies.

• planetgraph_nodes_list
• planetgraph_nodes_get
• planetgraph_node_types_list
• planetgraph_edges_list
• planetgraph_edges_get
• planetgraph_edges_for_node
• planetgraph_edge_types_list
• planetgraph_schema_describe

Search and querying

Find searchable properties and run supported Cypher safely.

• planetgraph_properties_search
• planetgraph_query_capabilities
• planetgraph_query_validate
• planetgraph_query_run

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.