> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Use Wordsmith from ChatGPT, Claude, Claude Code and other MCP hosts.

> [!NOTE]
>
> **Preview.** The MCP server is available to organisations in the Wordsmith MCP and files pilot. See the [preview overview](/preview).

The Wordsmith MCP server lets an AI assistant work in Wordsmith on a user's behalf. MCP (Model Context Protocol) is how assistants such as ChatGPT and Claude discover and call tools. The user connects once, signs in to Wordsmith and approves what the assistant may do. The assistant can then ask a Wordsmith agent, review, transform and draft documents, search case law and the organisation's repositories, build reports, manage tasks and files, share work and read usage.

## Connect

The server URL depends on where your organisation's data is held:

| Region | URL |
| - | - |
| Europe | `https://api.wordsmith.ai/mcp` |
| United States | `https://api.us.wordsmith.ai/mcp` |

**ChatGPT**

Add a custom connector with the URL above. ChatGPT opens the Wordsmith sign-in and consent screen.

**Claude**

In **Settings → Connectors**, add a custom connector with the URL above, then sign in when prompted.

**Claude Code**

```bash theme={null}
claude mcp add --transport http wordsmith https://api.wordsmith.ai/mcp
```

Then run `/mcp` in Claude Code and choose **Authenticate**.

Your role decides whether you can connect. Admins and full users can by default. Viewers cannot. An admin can allow it in a custom role with the **Connect AI apps over MCP** permission.

Sign-in uses [OAuth](/oauth). Wordsmith accepts only approved apps: ChatGPT, Claude, Wordsmith itself, and apps running on your own computer, such as Claude Code. On the consent screen the user chooses what the app may do.

## Tools

The server has 27 tools. Each one calls the same code as the REST endpoints linked from it, so results match field for field.

### Asking and waiting

| Tool | What it does | Scope | REST equivalent |
| - | - | - | - |
| `ask_wordsmith` | Ask a Wordsmith agent to answer, draft, review or redline, optionally with files. Waits for the answer, 15 seconds by default and at most 20. | `sessions:write` | [Create Question](/api-reference/agents/create-question) |
| `get_operation` | Wait for work a tool started, such as an answer, a review or a report run, and read its result. | The read scope of the work's type, such as `sessions:read` | [Get Operation](/api-reference/operations/get-operation) |
| `cancel_operation` | Stop work a tool started, such as a review, a document action, a draft or a report run. A question, an export or repository indexing cannot be stopped. | The write scope of the work's type, such as `reviews:write` | [Cancel Operation](/api-reference/operations/cancel-operation) |

### Finding and reading

| Tool | What it does | Scope | REST equivalent |
| - | - | - | - |
| `find_resources` | List or search one kind of object: agents, playbooks, blueprints, skills, repositories, reports, reviews, past sessions, members, teams, roles or company profiles. | The read scope of the kind, such as `playbooks:read` | The list routes, such as [List Agents](/api-reference/agents/list-agents) and [List Reviews](/api-reference/reviews/list-reviews) |
| `get_resource` | Read one object in detail, such as a playbook with its checks, a skill with its instructions and files, a report with its cells, a repository with its documents, or a task with its comments. It also reads who a repository, report, session, playbook, blueprint or task is shared with. | The read scope of the kind | The detail routes, such as [Get Playbook](/api-reference/playbooks/get-playbook), [Get Report](/api-reference/reports/get-report) and [Get Task](/api-reference/tasks/get-task) |
| `search_knowledge` | Search the organisation's repositories by meaning and return the best passages. | `repositories:read` | [Search Knowledge](/api-reference/search/search-knowledge) |
| `legal_research` | Search case law and legislation in public legal databases, or read one document's text. | `research:read` | [Search Research Sources](/api-reference/research/search), [Get Research Document](/api-reference/research/get-document) |
| `get_usage` | Read usage and value: sessions, active users, hours saved and cost saved. | `usage:read` | [Get Usage Summary](/api-reference/usage/get-usage-summary) |

### Documents

| Tool | What it does | Scope | REST equivalent |
| - | - | - | - |
| `review_document` | Review contracts against a playbook or your instructions. | `reviews:write` | [Create Review](/api-reference/reviews/create-review) |
| `get_review` | Read a review's status, finding counts and redline file, with a page of findings. | `reviews:read` | [Get Review](/api-reference/reviews/get-review), [List Findings](/api-reference/reviews/list-findings) |
| `update_review` | Make a tracked-changes DOCX from chosen findings' amendments. | `reviews:write` | [Generate Redline](/api-reference/reviews/generate-redline) |
| `transform_document` | Compare, redline from instructions, translate, redact, convert, merge, or accept tracked changes. | `files:write` | [Document actions](/api-reference/documents/compare) |
| `draft_document` | Draft a new document from instructions, or fill a blueprint. | `files:write` and `files:read` | [Create Draft](/api-reference/drafts/create-draft) |

### Repositories, reports, skills and sharing

| Tool | What it does | Scope | REST equivalent |
| - | - | - | - |
| `manage_repository` | Create or rename a repository, add files, create a folder, or remove a document. | `repositories:write` | [Repositories](/api-reference/repositories/create-repository) |
| `manage_report` | Build a report over files or a repository, add columns and rows, run it, and export it to Excel, CSV or JSON. | `reports:write` | [Reports](/api-reference/reports/create-report) |
| `manage_skill` | Create or change a skill, or import a `SKILL.md` folder with its files. | `skills:write`, and `files:read` to bundle files | [Skills](/api-reference/skills/create-skill) |
| `share_resource` | Share a repository, report, playbook, blueprint or task with a person or team, take their access away, or set who in the organisation can see it. | The write scope of the kind, such as `reports:write` | [Update Sharing](/api-reference/sharing/update-sharing) |
| `manage_organisation` | Change a member's roles or suspend them, create and edit teams and their members, invite people, resend or revoke invites, and edit a company profile. It cannot delete a team. The approving user's own admin rights still apply. | `directory:admin`, which a host gets only by asking for it. The tool is listed only on a connection with that scope; to get it, reconnect Wordsmith and grant admin access. | [Organisation](/api-reference/organisation/get-company-profile) |

### Tasks

| Tool | What it does | Scope | REST equivalent |
| - | - | - | - |
| `find_tasks` | Find tasks by person, status, due date or text. | `tasks:read` | [List Tasks](/api-reference/tasks/list-tasks) |
| `create_task` | Create a task or subtask. | `tasks:write` | [Create Task](/api-reference/tasks/create-task) |
| `update_task` | Change a task, attach files or links, follow it, or edit its comments. | `tasks:write` | [Update Task](/api-reference/tasks/update-task) |
| `add_task_comment` | Comment on a task, or reply to a comment. The requester does not see it. | `tasks:write` | [Add Comment](/api-reference/tasks/add-comment) |
| `reply_to_task_requester` | Reply to the person who requested a task, which can send an email. | `tasks:write` | [Add Thread Reply](/api-reference/tasks/add-thread-reply) |

### Files

| Tool | What it does | Scope | REST equivalent |
| - | - | - | - |
| `add_file` | Add a file from a URL, a chat attachment, or text. | `files:write` | [Import File](/api-reference/files/import-file), [Create File](/api-reference/files/create-file) |
| `create_file_upload`, `complete_file_upload` | Upload a file, for hosts that can run commands. | `files:write` | [Upload URL](/api-reference/files/upload-url), [Complete Upload](/api-reference/files/complete-upload) |
| `read_file` | Read a file's details, its text, or a download link. | `files:read` | [Get File](/api-reference/files/get-file), [Get File Text](/api-reference/files/get-file-text), [Get File Download](/api-reference/files/get-file-download) |

The assistant sees only the tools its approved scopes allow. A tool that works on existing files also needs `files:read`, and so does `draft_document`, which reads back the file it drafts. New files land in the user's private space.

Every tool tells the host whether it only reads, and hosts use that to decide when to ask the user. Six tools are marked destructive, so hosts confirm them more firmly: `update_task`, `share_resource` (it can take access away), `manage_repository` (removing a document deletes it and its file), `manage_report` (`update` overwrites a report's name and description), `manage_skill` (`update` replaces a skill's instructions and can detach files) and `manage_organisation` (it can suspend members, change roles, remove team members and revoke invites). Deleting tasks, reports, playbooks, skills, repositories and teams is REST-only.

The older tool names, such as `list_agents`, `get_wordsmith_answer` and `import_file`, keep working for now. Assistants no longer see them in the tool list.

## Long work takes a moment

An answer, a review, a document action, a draft, a report run or export, and adding files to a repository can each take longer than a few seconds. The tool that starts the work waits for it, 15 seconds by default and at most 20. If the work is not done by then, the tool returns an `operation_id`, and the assistant calls `get_operation` until it finishes. Each call waits up to 20 seconds. Hosts do this on their own; the user just waits for the reply.

## Files

Tools take files by `file_id`. An assistant gets one by:

* **Attaching a file in the chat.** ChatGPT passes attachments to `ask_wordsmith` and `add_file`.
* **Adding it from a URL or text** with `add_file`.
* **Uploading it** with `create_file_upload`, a `PUT` to the returned URL, then `complete_file_upload`.

An answer, a review, a document action and a draft list the files they produced by `file_id`. `read_file` gives a download link only when asked for one, and the link expires after 5 minutes.

## Disconnecting

To disconnect an app, remove the Wordsmith connector in the app. Its last access token stops working within an hour, and every grant ends after 60 days at most. Wordsmith does not yet list connected apps or let you disconnect one from inside Wordsmith; that comes before the preview ends.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.