---
title: MCP Integration
description: "Connect AI assistants to your docs with the hosted MCP connector or the local MCP server"
---

# MCP Integration

Syntext speaks the Model Context Protocol (MCP) so AI assistants — Claude, Cursor, VS Code, and any MCP-compatible client — can search, read, and even update your documentation directly.

There are two ways to connect:

<CardGroup cols={2}>
  <Card title="Hosted Connector (Recommended)" href="#hosted-connector-recommended">
    One URL, no install, no API keys. Sign in with your Syntext account via OAuth.
  </Card>
  <Card title="Local MCP Server" href="#local-mcp-server-api-key">
    Run the `@syntext/mcp-server` npm package locally with an API key.
  </Card>
</CardGroup>

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI models to data sources. Syntext exposes your documentation as context that AI assistants can query — and, with the hosted connector, act on.

## Hosted Connector (Recommended)

The hosted connector lives at a single endpoint:

```
https://api.syntext.dev/mcp
```

It uses OAuth 2.1 with dynamic client registration — no API keys to create or paste. The first time your AI client connects, a browser window opens where you sign in with your Syntext account and approve access. Everything is scoped to the projects your account can see.

### Claude (web / desktop)

Go to **Settings → Connectors → Add custom connector** and enter:

```
https://api.syntext.dev/mcp
```

### Claude Code

```bash
claude mcp add --transport http syntext https://api.syntext.dev/mcp
```

### Cursor

Add to `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "syntext": {
      "url": "https://api.syntext.dev/mcp"
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "syntext": {
      "type": "http",
      "url": "https://api.syntext.dev/mcp"
    }
  }
}
```

### Hosted connector tools

| Tool | Description |
|------|-------------|
| `list_projects` | List all documentation projects your account can access |
| `search_docs` | Semantic search across a project's documentation |
| `get_page` | Retrieve a rendered page by slug |
| `get_page_source` | Fetch the raw MDX source of a page |
| `update_page` | Commit an edit to a page (creates a Git commit + rebuild) |
| `ask_question` | Natural language Q&A against a project's docs |
| `list_pages` | List all pages in a project |
| `trigger_build` | Kick off a documentation build |
| `get_build_status` | Check the status of a build |

<Callout type="info">
  **Write access**: `update_page` and `trigger_build` act on your behalf using the project's GitHub App connection. Edits are committed to the linked repository and automatically rebuilt.
</Callout>

## Local MCP Server (API key)

Prefer to keep things local, or need to pin a single project? Run the `@syntext/mcp-server` npm package with an API key.

### VS Code / Cursor

1. Install the Syntext extension from the marketplace
2. Open the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
3. Run "Syntext: Configure MCP Server"
4. Enter your project ID and API key

Or manually add to your `settings.json`:

```json
{
  "mcp.servers": {
    "syntext": {
      "command": "npx",
      "args": ["@syntext/mcp-server"],
      "env": {
        "SYNTEXT_API_KEY": "stx_abc12345_...",
        "SYNTEXT_PROJECT_ID": "prj_abc123"
      }
    }
  }
}
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "syntext": {
      "command": "npx",
      "args": ["@syntext/mcp-server"],
      "env": {
        "SYNTEXT_API_KEY": "stx_abc12345_...",
        "SYNTEXT_PROJECT_ID": "prj_abc123"
      }
    }
  }
}
```

### Standalone Server

Install and run the MCP server directly:

```bash
npm install -g @syntext/mcp-server
syntext-mcp --project prj_abc123 --api-key stx_abc12345_...
```

## Usage

Once configured, the MCP server provides these capabilities:

### Search Documentation

The AI assistant can search your documentation semantically:

```
User: How do I configure authentication in this project?
Assistant: [searches docs] Based on the Authentication guide...
```

### Get Page Content

Retrieve specific documentation pages:

```
User: Show me the API reference for the /users endpoint
Assistant: [fetches page] Here's the documentation for the Users API...
```

### List Available Guides

Discover what documentation exists:

```
User: What topics are covered in the docs?
Assistant: [lists pages] The documentation includes guides on...
```

## Available Tools

The local MCP server exposes these tools to AI assistants:

| Tool | Description |
|------|-------------|
| `search_docs` | Semantic search across all documentation |
| `get_page` | Retrieve a specific page by slug |
| `list_pages` | List all available documentation pages |
| `get_api_endpoint` | Get details for a specific API endpoint |
| `ask_question` | Natural language Q&A using the AI assistant |

## Configuration Options

| Environment Variable | Description | Required |
|---------------------|-------------|----------|
| `SYNTEXT_API_KEY` | Your Syntext API key | Yes |
| `SYNTEXT_PROJECT_ID` | Project ID to query | Yes |
| `SYNTEXT_API_URL` | Custom API URL (default: `https://api.syntext.dev`) | No |

## Security

<Callout type="warning">
  **API Key Security**: The MCP server requires your API key to authenticate requests. Never commit API keys to version control. Use environment variables or a secure credential store.
</Callout>

The MCP server runs locally and communicates with the Syntext API over HTTPS. All queries are scoped to your project and respect your access controls.

## Troubleshooting

### Server not starting

Check that Node.js 18+ is installed:

```bash
node --version
```

Verify your API key is valid:

```bash
curl -H "Authorization: Bearer stx_abc12345_..." https://api.syntext.dev/v1/projects
```

### No results returned

Ensure your project has been indexed:

1. Go to the Syntext dashboard
2. Select your project
3. Check the "Search" section for indexing status

If not indexed, trigger a reindex:

```bash
curl -X POST https://api.syntext.dev/v1/projects/prj_abc123/search/reindex \
  -H "Authorization: Bearer stx_abc12345_..."
```

### Slow responses

The first query may be slower due to connection initialization. Subsequent queries should be faster.

For large documentation sites, consider:
- Increasing the search result limit
- Using more specific queries
- Enabling caching in your IDE settings

## Related

- [AI Assistant](/platform/ai-assistant) — Built-in chat widget for your docs
- [Search](/api-reference/search/query) — Programmatic search API
- [API Reference](/api-reference/overview) — Full API documentation