> ## Documentation Index > Fetch the complete documentation index at: https://docs.graphorlm.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Connect AI agents and coding assistants to your Graphor documents using the Model Context Protocol 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 files, URLs, GitHub repos, and YouTube videos; poll build status for file\_id Ask questions about your documents with conversational memory Extract structured data from documents using JSON Schema Retrieve relevant document chunks via semantic search ## 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](https://app.graphorlm.com) or see the [API Tokens guide](/guides/api-tokens) ### Quick Start with npx You can run the MCP Server directly via `npx` without installing anything: ```bash theme={null} 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: [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=graphor-mcp\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImdyYXBob3ItbWNwIl0sImVudiI6eyJHUkFQSE9SX0FQSV9LRVkiOiJNeSBBUEkgS2V5In19) Or manually add it to your Cursor `mcp.json` (found in **Cursor Settings > Tools & MCP > New MCP Server**): ```json theme={null} { "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](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22graphor-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22graphor-mcp%22%5D%2C%22env%22%3A%7B%22GRAPHOR_API_KEY%22%3A%22My%20API%20Key%22%7D%7D) Or manually add it to your VS Code `mcp.json` (found via **Command Palette > MCP: Open User Configuration**): ```json theme={null} { "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: ```bash theme={null} 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: ```json theme={null} { "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](https://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 1. Go to **Settings > Connectors > Add custom connector** 2. Fill in the **Name** (e.g. "Graphor") 3. Set the **Remote MCP server URL** to: ``` https://mcp.graphor.workers.dev/sse ``` 4. You will be redirected to log in through the OAuth flow 5. 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**): ```json theme={null} { "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**): ```json theme={null} { "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):** ```python theme={null} 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):** ```typescript theme={null} 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`](https://www.npmjs.com/package/mcp-remote) as a bridge: ```json theme={null} { "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`](https://www.npmjs.com/package/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: `auto`, `fast`, `balanced`, `accurate`, or `agentic`. Use `auto` for mixed PDFs (body + tables + scans in one document) — it routes each page to the cheapest parser that fits. ### 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: 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](https://example.com/whitepaper.pdf) and tell me when it's ready."* * *"Ingest the GitHub repo [https://github.com/owner/repo](https://github.com/owner/repo)."* * *"Ingest this YouTube video: [https://www.youtube.com/watch?v=abc123](https://www.youtube.com/watch?v=abc123)."* **Tool flow:** 1. Call `ingest_file` (or `ingest_url` / `ingest_github` / `ingest_youtube`) → receive `build_id` 2. Call `get_build_status` with `build_id` repeatedly until `success: true`. Status may be `Pending` (request received, build not started), then `Processing`, then `Completed`. 3. Use the returned `file_id` for all subsequent operations 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."* 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 'accurate' method to extract tables better."* * *"Reprocess this PDF with 'auto' to route each page to the cheapest parser that fits."* **Available methods:** `auto`, `fast`, `balanced`, `accurate`, `agentic` (`auto` is PDF-only) 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."* 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']."* 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:** ```json theme={null} { "type": "object", "properties": { "invoice_number": { "type": "string" }, "total_amount": { "type": "number" } }, "required": ["invoice_number", "total_amount"] } ``` Use `retrieve_chunks` to find the most relevant text chunks for a query without generating an answer. Useful for inspecting what context a downstream system might 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: ```bash theme={null} 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=` | Port to listen on (e.g., `3000`) | | `--socket=` | 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`): ```json theme={null} { "mcpServers": { "graphor_api": { "url": "http://localhost:3000", "headers": { "Authorization": "Bearer grlm_your_api_key_here" } } } } ``` ## Troubleshooting **Causes**: Missing or invalid API key **Solutions**: * 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](https://app.graphorlm.com) **Causes**: Node.js not installed, npx not available, or network issues **Solutions**: * 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 **Causes**: Server crashed or timed out **Solutions**: * Restart your MCP client * Check if another process is using the same port (remote mode) * Try a fresh install: `npx -y graphor-mcp@latest` **Causes**: Invalid code or SDK usage **Solutions**: * 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 Learn the full SDK API that your agent can use via the MCP server Detailed guide on ingesting documents, URLs, GitHub repos, and videos Ask questions and have conversations about your documents Extract structured data from documents with JSON Schema