Guides
View as Markdown Open in ChatGPT Open in Claude

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:

One URL, no install, no API keys. Sign in with your Syntext account via OAuth.

Run the @syntext/mcp-server npm package locally with an API key.

What is MCP?

The Model Context Protocol 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.

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

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

Cursor

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

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

VS Code

Add to .vscode/mcp.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

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.

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:

{
  "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:

{
  "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:

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

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.

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:

node --version

Verify your API key is valid:

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:

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
Was this page helpful?