Metadata-Version: 2.4
Name: annotators-mcp
Version: 0.1.0
Summary: MCP server for annotators.ai: let agents request human review of their own output
Author: annotators
License-Expression: MIT
Project-URL: Homepage, https://annotators.ai
Project-URL: Documentation, https://annotators.ai/docs
Keywords: mcp,model context protocol,claude,agents,human review,human-in-the-loop,annotation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: annotators<1,>=0.1.0
Requires-Dist: mcp<3,>=2
Dynamic: license-file

# annotators-mcp

An [MCP](https://modelcontextprotocol.io) server for [annotators.ai](https://annotators.ai). It lets
an agent ask for a human check of its own output, have items labeled, and run quick surveys, from
Claude Code, Claude Desktop or any other MCP client.

## Tools

| Tool | What it does |
|---|---|
| `list_tasks` | The tasks in your workspace, with the fields each one fills |
| `request_human_review` | Send a result the agent produced to be checked, or leave the output out to have the item labeled. Takes the agent's own confidence, `mode`, `hold` and `workforce` |
| `get_review_result` | Status, verdict (`approved`, `corrected`, `rejected` or `low_confidence`) and `final_output` |
| `run_survey` | Ask a number of people for their reaction to a message, headline or document |
| `get_survey_results` | A survey's status and aggregated results |

## Before you start

1. Sign up at [annotators.ai/console](https://annotators.ai/console/?signup), create a workspace,
   and make a key under **API keys**.
2. Create a task or two. A task says what an item looks like and which fields to fill. Tasks are
   created with the API or the [Python SDK](https://pypi.org/project/annotators/); the agent finds
   them with `list_tasks`.
3. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), which runs the server with
   `uvx annotators-mcp` without a separate install step. Or `pip install annotators-mcp` and use the
   `annotators-mcp` command in place of `uvx annotators-mcp` below.

## Claude Code

```bash
claude mcp add annotators -e ANNOTATORS_API_KEY=ak_... -- uvx annotators-mcp
```

Add `-s user` to have it in every project, not only the current one.

## Claude Desktop

Open **Settings → Developer → Edit Config** (that's `claude_desktop_config.json`, in
`~/Library/Application Support/Claude/` on macOS and `%APPDATA%\Claude\` on Windows) and add:

```json
{
  "mcpServers": {
    "annotators": {
      "command": "uvx",
      "args": ["annotators-mcp"],
      "env": { "ANNOTATORS_API_KEY": "ak_..." }
    }
  }
}
```

Restart Claude Desktop. If it can't start the server, put the full path from `which uvx` in
`command`; apps started from the Dock don't always see your shell's `PATH`.

Other MCP clients take the same command, arguments and environment.

## Who reviews

The tools leave `workforce` out unless the agent passes one, so items go to your workspace's
default: your own team (`private`), meaning the members of your console workspace and the reviewers
you invite. You review under **Review** in the console.

The annotators.org crowd (`open`, `vetted`) is on a waitlist. Join it under **Review** in the
console. Until your workspace has crowd access, a request for the crowd comes back as an error that
says so.

## Settings

| Variable | |
|---|---|
| `ANNOTATORS_API_KEY` | Required. A workspace key, `ak_...` |
| `ANNOTATORS_BASE_URL` | Defaults to `https://api.annotators.ai` |

## Links

- [annotators.ai](https://annotators.ai)
- [API reference](https://annotators.ai/docs)
- [Python SDK](https://pypi.org/project/annotators/)
