MCP Server

The Graphor MCP Server lets AI agents — such as Cursor, VS Code Copilot, Claude Code, and other MCP-compatible clients — interact with your Graphor project directly. Your agent can upload documents, ask questions, extract structured data, and perform semantic search, all without leaving your development environment.

Ingest & Manage

Ingest files, URLs, GitHub repos, and YouTube videos; poll build status for file_id

Chat & Ask

Ask questions about your documents with conversational memory

Extract Data

Extract structured data from documents using JSON Schema

Semantic Search

Retrieve relevant document chunks for custom RAG pipelines

How It Works

The Graphor MCP Server exposes 12 individual tools, one per SDK operation. Each tool maps directly to a Graphor API call and your agent calls them by name with typed parameters. The ingestion tools (ingest_file, ingest_url, ingest_github, ingest_youtube, and reprocess) are asynchronous: they return a build_id immediately, and you poll get_build_status until the job completes to obtain the file_id. All other operations (ask, extract, retrieve_chunks, get_elements, delete_source, list_sources) use file_id directly.

Installation

Prerequisites

Node.js 20+ (LTS recommended)
A Graphor API key — Create one in the dashboard or see the API Tokens guide

Quick Start with npx

You can run the MCP Server directly via npx without installing anything:

export GRAPHOR_API_KEY="grlm_your_api_key_here"
npx -y graphor-mcp@latest

Setup by Client

Cursor

Install the MCP server directly in Cursor using the button below:

Or manually add it to your Cursor mcp.json (found in Cursor Settings > Tools & MCP > New MCP Server):

{
  "mcpServers": {
    "graphor_api": {
      "command": "npx",
      "args": ["-y", "graphor-mcp@latest"],
      "env": {
        "GRAPHOR_API_KEY": "grlm_your_api_key_here"
      }
    }
  }
}

VS Code

Install the MCP server in VS Code by clicking the link below: Install Graphor MCP for VS Code Or manually add it to your VS Code mcp.json (found via Command Palette > MCP: Open User Configuration):

{
  "mcpServers": {
    "graphor_api": {
      "command": "npx",
      "args": ["-y", "graphor-mcp@latest"],
      "env": {
        "GRAPHOR_API_KEY": "grlm_your_api_key_here"
      }
    }
  }
}

Claude Code

Install the MCP server for Claude Code by running the following command in your terminal:

claude mcp add graphor_mcp_api --env GRAPHOR_API_KEY="grlm_your_api_key_here" -- npx -y graphor-mcp

You can also manually configure it in your .claude.json file (found in your home directory).

Other MCP Clients

For any MCP-compatible client, use the following configuration:

{
  "mcpServers": {
    "graphor_api": {
      "command": "npx",
      "args": ["-y", "graphor-mcp@latest"],
      "env": {
        "GRAPHOR_API_KEY": "grlm_your_api_key_here"
      }
    }
  }
}

See the full list of MCP-compatible clients at modelcontextprotocol.io/clients.

Remote MCP Server

For web-based AI clients (e.g. Claude.ai) or agentic frameworks (e.g. LangChain, CrewAI) that cannot run local npx processes, use the hosted remote MCP server. Authentication is handled via OAuth — a browser window will open for you to log in. Server URL:

https://mcp.graphor.workers.dev/sse

Claude.ai

Go to Settings > Connectors > Add custom connector
Fill in the Name (e.g. “Graphor”)
Set the Remote MCP server URL to:

https://mcp.graphor.workers.dev/sse

You will be redirected to log in through the OAuth flow
Once authenticated, Graphor tools will be available in your conversations

Claude Desktop (Remote)

Add the following to your Claude Desktop configuration file (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "graphor_api": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.graphor.workers.dev/sse"]
    }
  }
}

When you open Claude Desktop, a browser window will open for you to log in. After authenticating, the Graphor tools will appear in the bottom right of your conversation.

Cursor (Remote)

Add the following to your Cursor MCP configuration (Cursor Settings > Tools & MCP > New MCP Server):

{
  "mcpServers": {
    "graphor_api": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.graphor.workers.dev/sse"]
    }
  }
}

Agentic Workflows (LangChain, CrewAI, etc.)

For agentic frameworks that support MCP, connect to the remote server via SSE transport: LangChain (Python):

from langchain_mcp_adapters.client import MultiServerMCPClient

async with MultiServerMCPClient(
    {
        "graphor": {
            "url": "https://mcp.graphor.workers.dev/sse",
            "transport": "sse",
        }
    }
) as client:
    tools = client.get_tools()
    # Use tools with your LangChain agent

LangChain (TypeScript):

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
  graphor: {
    url: "https://mcp.graphor.workers.dev/sse",
    transport: "sse",
  }
});

const tools = await client.getTools();
// Use tools with your LangChain agent

Any MCP-compatible Client (Remote)

For any client that supports remote MCP servers via SSE, use the URL:

https://mcp.graphor.workers.dev/sse

For clients that only support stdio transport, use mcp-remote as a bridge:

{
  "mcpServers": {
    "graphor_api": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.graphor.workers.dev/sse"]
    }
  }
}

The OAuth flow will open a browser window on first connection. For headless environments, you may need to complete the OAuth flow beforehand or use mcp-remote as a local proxy.

Available Tools

Once installed, your agent has access to 12 tools covering the full Graphor API surface:

Ingestion

Tool	Required params	Optional params	Returns
`ingest_file`	`file_path` or (`file_content` + `file_name`)	`method`	`build_id`
`ingest_url`	`url`	`crawlUrls`, `method`	`build_id`
`ingest_github`	`url`	—	`build_id`
`ingest_youtube`	`url`	—	`build_id`
`get_build_status`	`build_id`	`suppress_elements`, `suppress_img_base64`, `page`, `page_size`	build status + `file_id` when complete. Status can be `Pending` (not started), `Processing`, `Completed`, or `Processing failed`

The method parameter controls the partitioning strategy: fast, balanced, accurate, vlm, or agentic.

Source Management

Tool	Required params	Optional params	Returns
`list_sources`	—	`file_ids`	list of sources with metadata
`reprocess`	`file_id`	`method`	`build_id`
`get_elements`	`file_id`	`page`, `page_size`, `suppress_img_base64`, `type`, `page_numbers`, `elementsToRemove`	paginated elements
`delete_source`	`file_id`	—	confirmation

Chat, Extraction & RAG

Tool	Required params	Optional params	Returns
`ask`	`question`	`file_ids`, `file_names`, `conversation_id`, `reset`, `output_schema`, `thinking_level`	answer + `conversation_id`
`extract`	`user_instruction`, `output_schema`	`file_ids`, `file_names`, `thinking_level`	`structured_output`
`retrieve_chunks`	`query`	`file_ids`, `file_names`	ranked text chunks

What Your Agent Can Do

With the MCP server, your agent can perform any operation available in the Graphor API:

Ingest Documents

Use ingest_file, ingest_url, ingest_github, or ingest_youtube to add sources. Each returns a build_id immediately — poll get_build_status to track progress and retrieve the file_id when processing completes.Example agent prompts:

“Ingest /Users/me/report.pdf using the agentic method.”
“Ingest https://example.com/whitepaper.pdf and tell me when it’s ready.”
“Ingest the GitHub repo https://github.com/owner/repo.”
“Ingest this YouTube video: https://www.youtube.com/watch?v=abc123.”

Tool flow:

Call ingest_file (or ingest_url / ingest_github / ingest_youtube) → receive build_id
Call get_build_status with build_id repeatedly until success: true. Status may be Pending (request received, build not started), then Processing, then Completed.
Use the returned file_id for all subsequent operations

List & Manage Sources

Use list_sources to see all ingested documents with their file_id, file_name, status, and metadata. Use delete_source to permanently remove a source by file_id.Example agent prompts:

“List all my sources and show their status.”
“Find the file_id for the document named ‘Q3 Report’.”
“Delete the source with file_id file_abc123.”

Reprocess Documents

Use reprocess to re-run the ingestion pipeline on an existing source with a different partitioning strategy. Returns a build_id — poll get_build_status as usual.Example agent prompts:

“Reprocess file_abc123 using the ‘agentic’ method for better accuracy.”
“Re-parse this PDF with the ‘vlm’ method to extract tables better.”

Available methods: fast, balanced, accurate, vlm, agentic

Inspect Parsed Elements

Use get_elements to retrieve the structured chunks/partitions of a processed source. Filter by element type, page numbers, or exclude unwanted types.Example agent prompts:

“Get the first 20 elements of file_abc123.”
“Show only the ‘Table’ elements from file_abc123.”
“Get elements from pages 3 to 5 of file_abc123.”

Chat with Documents

Use ask to pose natural-language questions about your sources. Maintain conversation memory by passing the conversation_id returned in each response. Scope to specific files using file_ids.Example agent prompts:

“Ask: what are the key findings in the ingested report?”
“Follow up: can you elaborate on the second finding?”
“Ask a question scoped to file_ids [‘file_abc123’, ‘file_def456’].”

Extract Structured Data

Use extract to pull typed data from documents by providing a natural-language instruction and a JSON Schema defining the output shape.Example agent prompts:

“Extract the invoice number and total amount from file_abc123.”
“From the contract, extract the parties, start date, and renewal terms.”

Example schema:

{
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string" },
    "total_amount": { "type": "number" }
  },
  "required": ["invoice_number", "total_amount"]
}

Semantic Search (RAG)

Use retrieve_chunks to find the most relevant text chunks for a query without generating an answer. Useful for building custom RAG pipelines or inspecting what context the model would use.Example agent prompts:

“Find chunks about payment terms in file_abc123.”
“Search across all sources for mentions of ‘data retention policy’.”

Running Remotely

You can run the MCP server as a remote HTTP server using Streamable HTTP transport:

export GRAPHOR_API_KEY="grlm_your_api_key_here"
npx -y graphor-mcp@latest --transport=http --port=3000

Flag	Description
`--transport=http`	Enables remote HTTP mode (Streamable HTTP transport)
`--port=<number>`	Port to listen on (e.g., `3000`)
`--socket=<path>`	Run on a Unix socket instead of a TCP port

Authentication for Remote Mode

Authorization can be provided via the Authorization header using the Bearer scheme, or via the x-graphor-api-key header:

Header	Equivalent Client Option	Security Scheme
`x-graphor-api-key`	`apiKey`	HTTPBearer

Remote Client Configuration

For clients connecting to a remote server (e.g., hosted at http://localhost:3000):

{
  "mcpServers": {
    "graphor_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer grlm_your_api_key_here"
      }
    }
  }
}

Troubleshooting

Authentication errors

Causes: Missing or invalid API keySolutions:

Verify your GRAPHOR_API_KEY is set correctly in the MCP configuration
Ensure the key starts with grlm_
Generate a new key in the Graphor dashboard

Server not connecting

Causes: Node.js not installed, npx not available, or network issuesSolutions:

Verify Node.js 20+ is installed: node --version
Ensure npx is available: npx --version
Try running the server manually first: npx -y graphor-mcp@latest
Check your MCP client logs for error messages

Server not responding

Causes: Server crashed or timed outSolutions:

Restart your MCP client
Check if another process is using the same port (remote mode)
Try a fresh install: npx -y graphor-mcp@latest

Agent execution errors

Causes: Invalid code or SDK usageSolutions:

Ask the agent to use the search_docs tool first to check the correct method signatures
Ensure your documents have been uploaded and processed before querying
Check that file names and IDs match what is in your project

Next Steps

SDK Overview

Learn the full SDK API that your agent can use via the MCP server

Ingest Sources

Detailed guide on ingesting documents, URLs, GitHub repos, and videos

Chat with Documents

Ask questions and have conversations about your documents

Data Extraction

Extract structured data from documents with JSON Schema

Get Started

Developers

Data Options

RAG Pipelines

Ingest & Manage

Chat & Ask

Extract Data

Semantic Search

How It Works

Installation

Prerequisites

Quick Start with npx

Setup by Client

Cursor

VS Code

Claude Code

Other MCP Clients

Remote MCP Server

Claude.ai

Claude Desktop (Remote)

Cursor (Remote)

Agentic Workflows (LangChain, CrewAI, etc.)

Any MCP-compatible Client (Remote)

Available Tools

Ingestion

Source Management

Chat, Extraction & RAG

What Your Agent Can Do

Running Remotely

Authentication for Remote Mode

Remote Client Configuration

Troubleshooting

Next Steps

SDK Overview

Ingest Sources

Chat with Documents

Data Extraction

Get Started

Developers

Data Options

RAG Pipelines

Ingest & Manage

Chat & Ask

Extract Data

Semantic Search

​How It Works

​Installation

​Prerequisites

​Quick Start with npx

​Setup by Client

​Cursor

​VS Code

​Claude Code

​Other MCP Clients

​Remote MCP Server

​Claude.ai

​Claude Desktop (Remote)

​Cursor (Remote)

​Agentic Workflows (LangChain, CrewAI, etc.)

​Any MCP-compatible Client (Remote)

​Available Tools

​Ingestion

​Source Management

​Chat, Extraction & RAG

​What Your Agent Can Do

​Running Remotely

​Authentication for Remote Mode

​Remote Client Configuration

​Troubleshooting

​Next Steps

SDK Overview

Ingest Sources

Chat with Documents

Data Extraction

How It Works

Installation

Prerequisites

Quick Start with npx

Setup by Client

Cursor

VS Code

Claude Code

Other MCP Clients

Remote MCP Server

Claude.ai

Claude Desktop (Remote)

Cursor (Remote)

Agentic Workflows (LangChain, CrewAI, etc.)

Any MCP-compatible Client (Remote)

Available Tools

Ingestion

Source Management

Chat, Extraction & RAG

What Your Agent Can Do

Running Remotely

Authentication for Remote Mode

Remote Client Configuration

Troubleshooting

Next Steps