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.

Every deployed doc site also exposes a public, read-only doc-site MCP endpoint at /_mcp when the MCP add-on is enabled.

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.

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

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.

Doc-Site MCP Endpoint

When the MCP Server add-on is enabled (Dashboard → Add-ons), every deployed doc site serves a public, unauthenticated MCP endpoint on its own domain:

https://your-docs-domain.com/_mcp

It exposes read-only docs tools — the same content as the site itself:

Tool	Description
`search_docs`	Semantic search across the site's documentation
`get_page`	Retrieve a page's content by slug
`ask_question`	AI Q&A with citations, scoped to this site

Generated API tools

If your docs include API reference pages (from an OpenAPI spec or pages with protocol/method/endpoint frontmatter), the build also generates one MCP tool per endpoint — so AI clients can call your API directly through the docs.

Generated tools proxy requests to your API, which requires a base URL. Precedence:

MCP add-on settings — the baseUrl field in Dashboard → Add-ons → MCP Server
baseUrl in syntext.json — used as the fallback

Without a base URL, generated API tools are not advertised to MCP clients (they could never execute), and calling one by name returns a configuration hint instead of an error. Path parameters in both {param} and :param styles are exposed as required tool inputs.

The add-on's allowed tools setting controls what's exposed: docs-only (just the three docs tools), all, or a custom tool allowlist.

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

Install the Syntext extension from the marketplace
Open the command palette (Cmd+Shift+P / Ctrl+Shift+P)
Run "Syntext: Configure MCP Server"
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

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:

Go to the Syntext dashboard
Select your project
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

AI Assistant — Built-in chat widget for your docs
Search — Programmatic search API
API Reference — Full API documentation