# MCP Server Setup

⏱️ **Time to Complete:** 10 minutes\
🎯 **Level:** Beginner\
💻 **Language:** TypeScript (MCP Server)

## What You'll Build

* ✅ Connect Graphlit to your MCP-compatible IDE (Cursor, Windsurf, Claude Desktop, Cline)
* ✅ Search your Graphlit project (Slack, Gmail, Notion, etc.) from your editor
* ✅ Query conversations, collections, feeds, and workflows
* ✅ Ingest new content or trigger workflows without leaving the IDE

[**📁 Graphlit MCP Server Repository**](https://github.com/graphlit/graphlit-mcp-server)

***

## Prerequisites

* Node.js 20+
* One of the MCP-aware IDEs (Cursor, Windsurf, Claude Desktop, or VS Code with Cline)
* Graphlit credentials in `.env` (from Getting Started guide):
  * `GRAPHLIT_ORGANIZATION_ID`
  * `GRAPHLIT_ENVIRONMENT_ID`
  * `GRAPHLIT_JWT_SECRET`
* `npm install -g graphlit-mcp-server` (or use `npx` in configs below)

{% hint style="info" %}
**Need Graphlit code examples?** Check out [Ask Graphlit](https://docs.graphlit.dev/resources/ask-graphlit) - an AI assistant that generates Graphlit SDK code in Python, TypeScript, or .NET. This MCP integration is for accessing your **data** (Slack, Gmail, content), not for code help.
{% endhint %}

***

## Setup

The Graphlit MCP Server exposes your actual Graphlit project: contents, feeds, collections, workflows, conversations, and specifications.

### Environment

Create `.env` with your Graphlit credentials (from Getting Started):

```bash
GRAPHLIT_ORGANIZATION_ID=your_org_id_from_portal
GRAPHLIT_ENVIRONMENT_ID=your_env_id_from_portal
GRAPHLIT_JWT_SECRET=your_jwt_secret_from_portal
```

Install and test locally:

```bash
npm install -g graphlit-mcp-server
# or npx graphlit-mcp-server
npx graphlit-mcp-server --test
```

### IDE Configuration

#### Cursor / Windsurf / Cline / Claude Desktop

```json
{
  "mcpServers": {
    "graphlit": {
      "command": "npx",
      "args": ["graphlit-mcp-server"],
      "env": {
        "GRAPHLIT_ORGANIZATION_ID": "${GRAPHLIT_ORGANIZATION_ID}",
        "GRAPHLIT_ENVIRONMENT_ID": "${GRAPHLIT_ENVIRONMENT_ID}",
        "GRAPHLIT_JWT_SECRET": "${GRAPHLIT_JWT_SECRET}"
      }
    }
  }
}
```

Restart your IDE. Graphlit will appear alongside other MCP tools.

***

## Key MCP Tools (from `graphlit-mcp-server`)

The server registers 60+ tools via `registerTools`:

| Category      | Examples                                                                                                 |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| Retrieval     | `queryContents`, `queryCollections`, `queryFeeds`, `queryConversations`, `retrieveRelevantSources`       |
| Conversations | `promptConversation` (streams via MCP channel)                                                           |
| Ingestion     | `ingestFile`, `ingestText`, `ingestWebPage`, `ingestEmail`, `ingestIssue`, `ingestMessage`, `ingestFeed` |
| Publishing    | `publishAudio`, `publishImage`                                                                           |
| Operations    | `configureProject`, `createCollection`, `addContentsToCollection`, `deleteContent`, `isContentDone`      |
| Enumerations  | `listSlackChannels`, `listNotionDatabases`, `listLinearProjects`, `listGoogleCalendars`, etc.            |

All enumerations, types, and arguments match the TypeScript SDK. For example:

```typescript
import {
  FeedTypes,
  FeedListingTypes,
  EmailListingTypes,
  SearchServiceTypes,
} from 'graphlit-client/dist/generated/graphql-types';
```

Use these same enums in MCP prompts when specifying properties.

***

## Example Prompts (Local Server)

### Search Company Knowledge

```
@graphlit query_contents search="redis failover" searchType=HYBRID limit=5
```

### Scope by Collection + Entity

```
@graphlit query_contents search="pricing" searchType=HYBRID collections=["${GRAPHLIT_COLLECTION_SUPPORT}"] observations=[{"type":"ORGANIZATION","observable":{"id":"${GRAPHLIT_ORG_ACME}"}}]
```

### Ingest a File

```
@graphlit ingest_file path="./runbooks/cache-playbook.pdf" workflow={"id":"${WORKFLOW_ID}"} isSynchronous=true
```

### Prompt a Conversation

```
@graphlit prompt_conversation id="${CONVERSATION_ID}" prompt="Summarize the last three incidents for Acme Corp and list remaining blockers."
```

The MCP server streams token updates back to the IDE when using `promptConversation`.

***

## Integrating with Other MCP Servers

Combine Graphlit with filesystem, GitHub, database or cloud MCP servers in one config:

```json
{
  "mcpServers": {
    "graphlit": { ... },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/code"]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}
```

Now your AI can pull:

* Local source files
* Open PRs and discussions
* Production incidents stored in Graphlit
* Slack, email, meetings tied to an account

***

## Production Tips

1. **Separate projects per tenant/team**: set `GRAPHLIT_ENVIRONMENT_ID` per MCP entry.
2. **Persist identifiers**: store collection/workflow IDs in env vars to reuse across prompts.
3. **Use `isContentDone`** before prompting to avoid stale context on newly ingested data.
4. **Secure secrets**: reference OS-level environment variables (`${VAR}`) instead of hardcoding values.
5. **Log tool output**: Cursor and Claude show MCP logs; use them to audit retrieved sources.

***

## Troubleshooting

* Run `npx graphlit-mcp-server --test` to validate credentials.
* Confirm Node.js 20+ and that `graphlit-client` installs without errors.
* OAuth-based tools (Slack, Gmail, GitHub) require tokens in the environment; follow instructions in the MCP server README.
* If tools fail, inspect IDE MCP logs; most errors surface there (`stdout`/`stderr`).

***

## Next Steps

* [**AI Agents**](https://docs.graphlit.dev/tutorials/ai-agents) – orchestrate tools from inside Graphlit agents.
* [**Context Engineering**](https://docs.graphlit.dev/tutorials/context-engineering) – design memory and retrieval strategies.
* [**Knowledge Graph**](https://docs.graphlit.dev/tutorials/knowledge-graph) – extract entities your MCP prompts can filter on.

With MCP + Graphlit, your IDE has direct access to the same semantic memory your production agents use. Build smarter tooling without leaving the editor.