> ## 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 or any MCP host: connect once, then review, transform, search and draft with about two dozen tools.

> [!WARNING]
>
> **Proposed — not available yet.** This page describes the MCP server as this proposal extends it. Today's server has asking, tasks and files only.

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, approves what the assistant may do, and can then ask it to "review this NDA against our playbook" or "compare these two drafts".

## Connect

The server URL is:

```
https://api.wordsmith.ai/mcp
```

**ChatGPT**

In **Settings → Connectors**, 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**.

Sign-in uses OAuth. Wordsmith accepts only the apps on its client allowlist, and your organisation can narrow that list. On the consent screen the user picks [scopes](/proposed/scopes). The assistant then sees only the tools those scopes allow.

## What the assistant can do

> **Ask and research**
>
> `ask_wordsmith` puts a question to a Wordsmith agent. `legal_research` searches case law and legislation, or commissions a research memo. `search_knowledge` searches your repositories.

> **Review contracts**
>
> `review_document` runs a playbook, a set of instructions, or a counterparty-edits review. `get_review` reads findings. `update_review` generates the redline or applies decisions.

> **Work on documents**
>
> `transform_document` compares, redlines, translates, redacts, converts, accepts changes and merges. `draft_document` drafts a new document, from scratch or from a blueprint.

> **Organise work**
>
> Tasks, repositories, reports, sharing, and usage and value, through a handful of tools.

The full list, with each tool's scope and arguments, is in [MCP tools](/proposed/mcp-tools).

## Why so few tools

Every tool an assistant loads is described in its context on every turn. Long tool lists cost tokens and make assistants pick the wrong tool more often. So the MCP server has 26 tools shaped around jobs, while the [REST API](/proposed/overview) has an endpoint for every action. The functionality is the same: each tool calls the same code as the matching REST endpoints.

To keep the list short, related actions share a tool. `transform_document` takes an `action` (`compare`, `translate`, `redact`, …) and `find_resources` takes a `kind` (`playbook`, `repository`, `report`, …). Actions are only grouped when they need the same scope and carry the same risk, so the assistant's approval prompts stay accurate.

## Long-running tools

An MCP tool call has the same 29-second limit as any request, and a review takes minutes. Long-running tools handle this for the assistant:

**1. The tool waits first**

`review_document`, `transform_document` and the other long-running tools take `wait_seconds` (default 15, maximum 20). If the work finishes in that time, the tool returns the result directly.

**2. Otherwise it returns an operation**

The result says `status: "running"` and gives an `operation_id`, the progress so far, and when to check again.

**3. The assistant waits on the operation**

`get_operation(operation_id, wait_seconds=20)` holds for up to 20 seconds and returns as soon as the work is done. A three-minute review takes about nine calls.

```json Result while still running theme={null}
{
  "status": "running",
  "operation_id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "progress": { "stage": "checks", "completed": 14, "total": 32 },
  "poll_after_seconds": 5,
  "next_step": "Call get_operation with this operation_id and wait_seconds=20 until status is succeeded."
}
```

Retrying a tool call never starts the work twice. The server derives an idempotency key from the call's arguments.

## Files

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

* **Attaching a file in the chat.** In ChatGPT, attachments are passed to tools that accept them, such as `add_file` and `ask_wordsmith`.
* **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`. This is for hosts that can run commands, such as Claude Code.

Documents Wordsmith produces, such as redlines and translations, come back as new `file_id`s. `read_file` returns their text or a short-lived download link.

## Safety

* **No deletes.** An assistant cannot delete anything. Deletes are in the REST API only.
* **Admin changes only with an admin scope the app asked for.** An assistant can read the company profile, members, teams and roles. It can invite, suspend, change roles or edit teams only through `manage_organisation`, which needs `directory:admin`. That scope is never granted by default: the app must ask for it and the user must approve it, and the assistant can then do only what that user may do in Wordsmith. The tool is marked destructive, so hosts ask before every change, and it cannot delete a team.
* **Sharing within the rules the app applies.** `share_resource` can share with, or unshare from, people and teams in the user's own organisation. It needs the user to be an admin of the resource, cannot grant more than the user's own access, and cannot make anything public. It is marked destructive, so hosts ask before every change.
* **Accurate approval prompts.** Each tool is marked read-only, write or destructive, and as reaching outside Wordsmith where it does. `reply_to_task_requester`, which emails someone outside Wordsmith, has its own tool, so hosts always ask before sending.
* **The user's own permissions.** Every tool acts as the signed-in user, limited further by the approved scopes.


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