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

# MCP overview

> What the ai-cmo.dev MCP server is and when to use it.

The ai-cmo.dev MCP server (`ai-cmo-mcp`) is a local stdio process that gives an AI assistant (Claude Code, or any MCP client) read/write access to an ai-cmo.dev workspace by proxying the REST API.

## Architecture

```text theme={null}
Assistant  ⇄  stdio  ⇄  ai-cmo-mcp  ⇄  HTTPS  ⇄  ai-cmo.dev API
```

The server runs on your machine. It never exposes an HTTP endpoint — communication is exclusively over the MCP stdio transport. The binary connects to the ai-cmo.dev web app over HTTPS (or a local dev instance) and authenticates via an API key or a device authorization flow.

## MCP vs REST API directly

| Use case                                                   | Recommended path |
| ---------------------------------------------------------- | ---------------- |
| Claude Code reading scores, recommendations, runs, reports | MCP              |
| Automated CI/CD pipeline                                   | REST API         |
| Dashboard frontend                                         | REST API         |
| Ad-hoc analysis in the assistant's chat                    | MCP              |

## Capabilities

* **10 tools** — reading scores, scoreboards, recommendations, runs, reports, workspace identity, and assistant chat; one mutating tool for guarded recommendation lifecycle transitions.
* **No resources or prompts** — the server only exposes tools. Every interaction is a tool call.

## Requirements

* Node.js 20 or later (for `npx` and the `ai-cmo-mcp` package)
* The ai-cmo.dev web app running at `http://127.0.0.1:3000` (or a remote instance via `AICMO_BASE_URL`)

## Next steps

<CardGroup cols={2}>
  <Card title="Install the server" icon="download" href="/mcp/install">
    Add the server to your MCP client and authorize it in the browser.
  </Card>

  <Card title="Authorization" icon="key" href="/mcp/authorization">
    How credentials resolve and how the device flow works.
  </Card>

  <Card title="Tool reference" icon="wrench" href="/mcp/tools">
    All 10 tools, their parameters, scopes, and example results.
  </Card>

  <Card title="Usage examples" icon="message" href="/mcp/usage-examples">
    Natural-language prompts and a worked multi-step workflow.
  </Card>
</CardGroup>