---
title: MCP tools reference
description: Look up the local authoring and deployed-site tools available through Thally's MCP servers.
url: https://pr-7-a9c4e9fe1b6c.thally.app/guides/mcp-server
---

# MCP tools reference

Look up the local authoring and deployed-site tools available through Thally's MCP servers.

`@thallylabs/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI tools — Claude Code, Claude Desktop, Cursor, Windsurf — create, read, update, and migrate Thally documentation projects through natural language.

## Setup

Add `@thallylabs/mcp` to your coding agent or desktop client:

#### Codex

```bash
codex mcp add thally -- npx -y @thallylabs/mcp
```

#### Claude Code

```bash
claude mcp add thally -- npx -y @thallylabs/mcp
```

#### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "thally": {
      "command": "npx",
      "args": ["-y", "@thallylabs/mcp"]
    }
  }
}
```

#### Cursor / Windsurf

Add to your MCP settings:

```json
{
  "mcpServers": {
    "thally": {
      "command": "npx",
      "args": ["-y", "@thallylabs/mcp"]
    }
  }
}
```

Once connected, you can talk to your docs like a collaborator: *"Add a page about webhooks to the Guides tab"* or *"Migrate the Stripe docs into a new project"*.

---

## Tools

### Project management

#### `create_project`

Scaffolds a project from the current immutable starter release. The release
pins one exact public runtime revision and is shared by the CLI, MCP, migration,
and Thally Cloud creation flows.

```
Create a new Thally project at ~/dev/my-docs with the name "Acme Docs"
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path for the new project |
| `projectName` | No | Displayed in header and metadata |
| `description` | No | Used for SEO and OpenGraph |
| `brandPreset` | No | `primary` or `secondary` |
| `repoUrl` | No | GitHub URL for "Edit on GitHub" links |
| `install` | No | Run `npm install` after scaffolding (default: `true`) |

---

#### `add_page`

Creates a new MDX page and registers it in `docs.json`.

```
Add a page called "Authentication" to the Guides tab under a "Security" group
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path to the Thally project |
| `pageId` | Yes | e.g. `guides/private-docs` — no `.mdx` extension |
| `title` | Yes | Page title (frontmatter) |
| `description` | No | Page description (frontmatter) |
| `content` | No | MDX body (placeholder used if omitted) |
| `tab` | No | Tab name (defaults to first tab) |
| `group` | No | Group name (defaults to first group) |
| `position` | No | `start` or `end` (default: `end`) |

---

#### `add_tab`

Adds a new top-level tab to the navigation.

```
Add a "SDK Reference" tab to the project
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path to the Thally project |
| `tabName` | Yes | Tab label |
| `href` | No | If set, creates a redirect link tab (e.g. `/changelog`) |
| `position` | No | `start` or `end` (default: `end`) |

---

#### `update_page`

Updates the frontmatter or body of an existing page.

```
Update the "Getting Started" page to mention the new --yes flag
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path to the Thally project |
| `pageId` | Yes | Page to update |
| `title` | No | New title |
| `description` | No | New description |
| `content` | No | Replaces the existing body |
| `mergeFrontmatter` | No | Additional frontmatter fields to merge |

---

#### `list_pages`

Lists all pages in a project, organized by tab and group.

```
Show me all the pages in my docs project
```

---

### Migration

#### `migrate_docs`

Creates a new Thally project from the current canonical template, then imports a public docs site or GitHub docs repository into it. The target directory must be new or empty; the tool never reuses an existing site's runtime.

```
Migrate https://github.com/example/docs into a new Thally project at /tmp/example-docs
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `sourceUrl` | Yes | Public docs URL or GitHub repository URL |
| `projectDir` | Yes | New or empty target directory |
| `branch` | No | Git branch to clone (auto-detected by default) |
| `docsDir` | No | Docs subdirectory in the repo (auto-detected) |
| `platform` | No | `mintlify` or `docusaurus`; omit for auto-detection |
| `maxPages` | No | Maximum number of live-site pages to import (`1`–`1000`) |
| `apiKey` | No | Anthropic API key for non-Markdown conversion |

#### `import_docs`

Imports documentation into an existing Thally project without replacing its runtime. Use this tool only when you intentionally want an in-place content and navigation merge.

```
Import https://github.com/example/api-docs into the existing Thally project at /workspace/docs
```

The source options match `migrate_docs`; `projectDir` must point to an existing Thally project.

---

### Reading & searching

These tools let AI agents query your docs as context — useful for building AI features on top of your documentation.

#### `search_docs`

Searches all pages by keyword and returns ranked results.

```
Search the docs for anything about rate limiting
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path to the Thally project |
| `query` | Yes | Search query |
| `limit` | No | Max results to return (default: `5`) |

---

#### `read_page`

Reads the full content of a single page by ID.

```
Read the "guides/private-docs" page
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path to the Thally project |
| `pageId` | Yes | e.g. `guides/private-docs` |

---

#### `get_context`

Returns the most relevant docs content for a topic, within a token budget. Ideal for grounding AI responses in your documentation.

```
Get context about the authentication flow for up to 4000 tokens
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path to the Thally project |
| `topic` | Yes | Topic or question |
| `maxTokens` | No | Token budget (default: `4000`) |

---

### Agent-native (deployed site)

These tools query a **deployed** Thally site over HTTP — they use the same indexes and reports that power the live site, so an agent can reason about docs it didn't scaffold.

#### `semantic_search`

Runs hybrid (full-text + vector) search against a deployed site's `/api/search` — the same Orama index as the in-app command palette.

```
Semantic-search https://docs.example.com for "rotating API keys"
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `siteUrl` | Yes | Base URL of the deployed Thally site |
| `query` | Yes | Natural-language search query |
| `limit` | No | Max results (default: `8`) |
| `mode` | No | `hybrid` (default) or `fulltext` |

---

#### `agent_readiness`

Fetches the Agent Readiness Score (0–100) for a deployed site — the same report as `/api/agent-readiness` and `thally check`, including per-signal subscores and the specific pages dragging the score down.

```
What's the agent readiness score for https://docs.example.com?
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `siteUrl` | Yes | Base URL of the deployed Thally site |
| `minScore` | No | Threshold (0–100); flags pass/fail in the summary |

---

### Quality

#### `lint_project`

Checks a project for errors and warnings: broken nav references, orphan files, missing frontmatter.

```
Check my docs project for any issues
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path to the Thally project |
| `fix` | No | Auto-add orphan pages to the nav (default: `false`) |

---

### Internationalization

#### `translate_docs`

Translates documentation pages to a secondary locale using Claude AI. Requires an `i18n` block in the project's `docs.json`. Translated MDX files are written to `src/content/{locale}/` for you to review and commit.

```
Translate my docs to Spanish
```

```
Translate only the introduction and quickstart pages to French
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Path to the Thally project |
| `locale` | Yes | Target locale code, e.g. `"es"`, `"fr"` |
| `pages` | No | Array of page IDs to translate (omit for all pages) |
| `force` | No | Overwrite existing translation files (default: `false`) |
| `apiKey` | No | Anthropic API key (falls back to `ANTHROPIC_API_KEY`) |
| `model` | No | Claude model to use (default: `claude-sonnet-4-6`) |

See [Multi-Language Support](/guides/multi-language) for full setup instructions.

---

### Product changes (self-managed workflow)

#### `sync_from_repo`

Analyzes a merged pull request using the local project's `docs.json` tracking
configuration. It previews the documentation task by default, or dispatches it
to the docs repository so the review-gated docs agent can draft a pull request.

For Cloud Track, connect Product sources and Knowledge surfaces in Thally
Cloud. The managed pipeline uses durable GitHub intake, Product Knowledge
impact, and scoped repository access; it does not depend on this MCP tool.

```
Preview the docs task for pull request 482 in acme/widget
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectDir` | Yes | Thally project containing the tracking configuration. |
| `repo` | Sometimes | Product repository as `owner/repo`; optional when exactly one repo is tracked. |
| `pr` | No | Merged pull request number; defaults to the latest merge on the tracked branch. |
| `dryRun` | No | Preview without dispatching. Defaults to `true`. |
| `docsRepo` | For dispatch | Documentation repository as `owner/repo`; required when `dryRun` is `false`. |

Dispatch requires `THALLY_GITHUB_TOKEN` or a connected GitHub App with access
to the docs repository. The tool never merges the generated documentation pull
request.