@graphite-atlas/mcp-server

v1.6.0

Published

14 hours ago

Model Context Protocol server for Graphite Atlas

0High
0Medium
0Low

fuzeelogik

mcp model-context-protocol graphite-atlas knowledge-graph claude

Graphite Atlas MCP Server

A Model Context Protocol (MCP) server that provides Claude and other AI assistants with access to your Graphite Atlas knowledge graphs.

Features

🗺️ Atlas Management (5 tools): Create, read, update, and delete knowledge graphs
📍 Point Operations (6 tools): Add and manage nodes (entities) in your graphs
🔗 Path Operations (6 tools): Create and manage edges (relationships) between points
👁️ View Management (10 tools): Organize points into views with folders and visibility controls
📦 Batch Operations (1 tool): Create multiple points and paths in a single atomic call
🧠 Brain Dump (2 tools): AI-powered graph generation from unstructured text
✅ Validation & Ontology (4 tools): Validate types, find duplicates, and browse the ontology
📊 Analytics (4 tools): PageRank, betweenness centrality, neighborhoods, isolated nodes
🧮 MAGE Algorithms (7 tools): Community detection, shortest path, node similarity, and more
📋 Context Brief (2 tools): Generate atlas summaries for use as LLM system prompts

47 tools across 10 categories. The server includes built-in ontology context so Claude knows what Atlas is and how to use it without needing extra prompts.

Installation

From npm

npm install -g @graphite-atlas/mcp-server

From source

cd mcp
npm install
npm run build

Quick Start

1. Generate a JWT Token

Before using the MCP server, you need a JWT access token from Graphite Atlas:

Log in to https://graphiteatlas.com
Navigate to Profile → API Apps tab
Create a new API app:
- Click "New App"
- Name: "Claude MCP"
- Description: "MCP server for Claude integration"
- Click "Create App"
Generate a JWT token:
- Click "Generate Token" on your new app
- Token Name: "Claude"
- Environment: Production (or Development for testing)
- Scopes: Select "*" (Full Access) for easiest setup
- Expires In: 90 days (recommended)
- Click "Generate Token"
Copy your JWT token — it will only be shown once!

2. Configure Your Client

Claude Code (CLI)

Add to ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "graphite-atlas": {
      "command": "npx",
      "args": ["@graphite-atlas/mcp-server"],
      "env": {
        "GRAPHITE_ACCESS_TOKEN": "your_token_here",
        "GRAPHITE_API_URL": "https://graphiteatlas.com"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "graphite-atlas": {
      "command": "npx",
      "args": ["@graphite-atlas/mcp-server"],
      "env": {
        "GRAPHITE_ACCESS_TOKEN": "your_token_here",
        "GRAPHITE_API_URL": "https://graphiteatlas.com"
      }
    }
  }
}

3. Restart and Test

Restart your client, then ask Claude:

"List my atlases"

Claude should use the list_atlases tool to fetch and display your knowledge graphs.

Available Tools

Atlas Management (5 tools)

| Tool | Description | |------|-------------| | list_atlases | List all knowledge graphs | | get_atlas | Get details of a specific atlas | | create_atlas | Create a new knowledge graph | | update_atlas | Update atlas name or description | | delete_atlas | Delete an atlas permanently |

Point Operations (6 tools)

Points are nodes in the graph — people, processes, systems, outcomes, etc.

| Tool | Description | |------|-------------| | list_points | List all points in an atlas | | get_point | Get a specific point by ID | | create_point | Create a new point (name, type, properties) | | update_point | Update a point's name, type, or properties | | delete_point | Delete a point | | search_points | Search points by name or type |

Valid point types: Person, Position, Group, Organization, Vendor, Process, Step, Review, Decision, Approval, Handoff, Task, Sequence, StepGroup, And, Or, System, Artifact, API, Equipment, Skill, Transport, Outcome, Metric, Physical Site, Date, TimeRange, Temporal, AbsoluteDate, RelativeOffset

Use lookup_ontology to browse types and their descriptions before creating.

Path Operations (6 tools)

Paths are typed relationships between points.

| Tool | Description | |------|-------------| | list_paths | List all paths in an atlas | | get_path | Get a specific path by ID | | create_path | Create a path between two points | | update_path | Update a path's type or properties | | delete_path | Delete a path | | search_paths | Search paths by type |

Valid path types: has_role, reports_to, member_of, responsible_for, assigned_to, has_skill, has_subsidiary, operates_under, has_interest, performs, has_step, followed_by, followed_by_if, creates_output, from_person, to_person, handoff_of, needs_input, uses_resource, measured_by, impacts, located_in, happens_before, happens_after, simultaneous_with, has_deadline, part_of

Use lookup_ontology with paths_for_type to see which paths are valid for a given point type.

View Management (10 tools)

Views organize subsets of points into named collections with layout and visibility controls.

| Tool | Description | |------|-------------| | list_views | List all views in an atlas | | get_view | Get view details | | create_view | Create a new view | | update_view | Update view settings | | delete_view | Delete a view | | get_view_points | Get points in a view with visibility state | | add_points_to_view | Add/show points in a view | | remove_point_from_view | Remove/hide a point from a view | | get_view_hierarchy | Get the folder tree for views |

Batch Operations (1 tool)

| Tool | Description | |------|-------------| | batch_create | Create multiple points and paths in one atomic call |

Batch create accepts point names (not IDs) for path source/target, resolving them automatically. Useful for building out an entire org structure or process map in one call.

Brain Dump (2 tools)

| Tool | Description | |------|-------------| | brain_dump | Generate a knowledge graph from unstructured text using AI | | get_brain_dump_status | Check the status of a brain dump operation |

Pass meeting notes, transcripts, or any narrative text and the AI will extract structured points and paths.

Validation & Ontology (4 tools)

| Tool | Description | |------|-------------| | validate_points | Validate point types against the ontology before creation | | validate_paths | Validate path types against the ontology before creation | | find_similar_points | Find existing points similar to a proposed name (duplicate detection) | | lookup_ontology | Browse valid types, categories, and path constraints |

`lookup_ontology` Query Modes

| Mode | Description | |------|-------------| | point_types | List all valid point types, optionally filtered by category | | path_types | List all valid path types with source/target constraints | | paths_for_type | Show all valid paths from/to a specific point type | | search | Case-insensitive search across type names and descriptions |

Analytics (4 tools)

| Tool | Description | |------|-------------| | get_page_rank | Rank nodes by influence/authority | | get_betweenness_centrality | Find bridge nodes connecting communities | | get_node_neighborhood | Get a node's immediate connections | | find_isolated_nodes | Find disconnected nodes with no relationships |

MAGE Graph Algorithms (7 tools)

Advanced algorithms powered by Memgraph's MAGE library.

| Tool | Description | |------|-------------| | mage_pagerank | PageRank with configurable damping factor | | mage_betweenness_centrality | Betweenness centrality (normalized) | | mage_detect_communities | Community detection via Leiden algorithm | | mage_connected_components | Find disconnected subgraphs | | mage_node_similarity | Jaccard similarity between nodes | | mage_shortest_path | BFS shortest path between two nodes | | mage_degree_centrality | Most connected nodes (in/out/both) |

Context Brief (2 tools)

Generate structured summaries of your atlas data for use as LLM system prompts or persistent project context.

| Tool | Description | |------|-------------| | get_atlas_brief | Get a structured context brief — entity types, key nodes, query patterns, and suggested questions | | generate_setup | Generate CLAUDE.md content combining the atlas brief with MCP tool instructions |

Working with Context Briefs

Start each session with a brief:

"Give me a brief for atlas <id>"

Claude will call get_atlas_brief and have full context about your data before you ask any questions.

Generate a persistent CLAUDE.md:

"Generate setup content for atlas <id> and save it to CLAUDE.md"

Claude will call generate_setup and write a CLAUDE.md file that combines the atlas brief with tool usage instructions. Future sessions will load this context automatically without needing to call get_atlas_brief each time.

MCP Resources:

The server also exposes each atlas as an MCP resource at atlas://<atlas_id>/brief. Some MCP clients (e.g. Claude Code) can list and read these resources directly. Reading one returns the same brief markdown as get_atlas_brief.

Note: MCP resource descriptions appear in list_resources output but are not automatically injected into context. Call get_atlas_brief or paste the generate_setup output into CLAUDE.md for persistent context.

JWT Scopes

When generating your JWT token, select the scopes you need:

| Scope | Required For | Description | |-------|-------------|-------------| | * | All operations | Full access to all resources (recommended) | | read:atlases | List/get atlases | View your knowledge graphs | | write:atlases | Create/update atlases | Create and modify atlases | | delete:atlases | Delete atlases | Permanently delete atlases | | read:points | List/get points | View nodes in your graphs | | write:points | Create/update points | Add and modify nodes | | delete:points | Delete points | Remove nodes | | read:paths | List/get paths | View relationships | | write:paths | Create/update paths | Add and modify relationships | | delete:paths | Delete paths | Remove relationships | | read:schema | Get schemas | View atlas ontology schemas | | use:llm | Brain dump | AI-powered graph generation | | use:embeddings | Semantic search | AI-powered semantic search |

Recommended: * (Full Access)

Hosted / Remote Usage (Streamable HTTP Transport)

If you just want a remote endpoint, one is already running:

https://graphiteatlas.com/api/mcp

It's served by the Atlas app, supports OAuth 2.1 (dynamic client registration, no token to paste) as well as Authorization: Bearer <token>, and needs nothing installed. This is the URL to give Claude.ai, Cursor, VS Code, and Microsoft Copilot Studio.

Starting in v1.5.0 this package also ships the streamable HTTP transport itself, for self-hosting against your own Atlas instance or for local development.

Quick start (self-hosted)

# Start HTTP server on port 3000
node dist/index.js --http
# or: MCP_TRANSPORT=http node dist/index.js
# or: PORT=8080 node dist/index.js --http

The MCP endpoint is POST /mcp (and GET /mcp for SSE). A GET /health readiness probe is also available.

Authentication: every request must carry Authorization: Bearer <your-token>. A missing header returns HTTP 401.

# Quick test with curl
curl -i -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

See docs/INTEGRATIONS.md for full configuration snippets for Claude Desktop, Claude.ai / Managed Agents, Cursor, VS Code, and Copilot Studio, plus self-hosting guides (Vercel, Docker).

End-user documentation lives at docs.graphiteatlas.com.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GRAPHITE_ACCESS_TOKEN | JWT access token (required for stdio transport) | - | | GRAPHITE_API_URL | Graphite Atlas API base URL | https://graphiteatlas.com | | MCP_TRANSPORT | Transport mode: stdio or http | stdio | | PORT | Port for HTTP transport | 3000 |

Development

npm run build        # Compile TypeScript
npm run watch        # Watch mode
npm run dev          # Dev mode with tsx
npm run lint         # ESLint
npm run typecheck    # TypeScript type check
npm test             # Run tests

Troubleshooting

"GRAPHITE_ACCESS_TOKEN environment variable is required"

You need to provide a valid JWT access token. See Quick Start.

"Failed to connect to Graphite Atlas API"

Check that:

Your access token is valid (not expired)
The API URL is correct
You have network connectivity

"API Error (401): Unauthorized"

Your access token may be expired. Generate a new one from Profile → API Apps.

Tools not appearing in Claude

Check client logs for errors
Verify your config file syntax is valid JSON
Restart your client after config changes

Security

Never commit your access token to version control
Never share your access token publicly
Rotate tokens regularly
Use minimal scopes required for your use case

License

MIT

Support

Documentation: https://docs.graphiteatlas.com
Issues: https://github.com/graphiteatlas/mcp/issues

Built with ❤️ by the Graphite Atlas team