# MCP server
URL: https://docs.clearly-ai.com/docs/mcp
Description: Connect AI assistants to Clearly AI using the Model Context Protocol (MCP) server.
The Clearly AI MCP server lets AI assistants — such as Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients — interact with Clearly AI on your behalf. You can create Projects, run Reviews, and retrieve Review results through natural language conversation with your AI assistant.

All actions taken through the MCP server run as you, using your Clearly AI identity and permissions.

## What you need [#what-you-need]

* A Clearly AI account with access to at least one Organization.
* An MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, VS Code with Copilot, or any client that supports the MCP HTTP transport).
* Your tenant URL, typically `https://{tenant}.clearly-app.com`.

## Connect your AI client [#connect-your-ai-client]

Add the Clearly AI MCP server to your client's configuration. The server uses HTTP transport with OAuth 2.0 authentication — your client will open a browser window to authenticate you the first time you connect.

### Configuration [#configuration]

Add the following to your MCP client configuration:

```json
{
  "mcpServers": {
    "clearly": {
      "type": "http",
      "url": "https://{tenant}.clearly-app.com/mcp"
    }
  }
}
```

Replace `{tenant}` with your Clearly AI tenant name. Your tenant name is the subdomain in your Clearly AI URL.

### Client-specific setup [#client-specific-setup]

<Accordions>
  <Accordion title="Claude Desktop">
    1. Open **Settings > Developer > Edit Config**.
    2. Add the `clearly` entry shown above to the `mcpServers` object.
    3. Save and restart Claude Desktop.
    4. When prompted, authenticate through the browser window that opens.
  </Accordion>

  <Accordion title="Claude Code">
    Run the following command to add the Clearly AI MCP server:

    ```bash
    claude mcp add --transport http clearly https://{tenant}.clearly-app.com/mcp
    ```

    When you next start a conversation that uses the server, Claude Code will prompt you to authenticate.
  </Accordion>

  <Accordion title="Cursor">
    1. Open **Settings > MCP**.
    2. Click **Add new MCP server**.
    3. Set the type to **HTTP** and the URL to `https://{tenant}.clearly-app.com/mcp`.
    4. Save and authenticate when prompted.
  </Accordion>

  <Accordion title="VS Code (Copilot)">
    Add the configuration to your VS Code `settings.json` or `.vscode/mcp.json`:

    ```json
    {
      "mcp": {
        "servers": {
          "clearly": {
            "type": "http",
            "url": "https://{tenant}.clearly-app.com/mcp"
          }
        }
      }
    }
    ```
  </Accordion>
</Accordions>

## What you can do [#what-you-can-do]

Once connected, ask your AI assistant to perform Clearly AI tasks in natural language. The MCP server exposes tools that the assistant calls automatically based on your requests. Your AI client will list the available tools when you connect.

Some tools read data and others change Clearly AI resources. The tools available to a client depend on your Clearly AI permissions.

The available capabilities include listing and managing Projects and Reviews, retrieving Review results, and working with [Review Templates](https://docs.clearly-ai.com/docs/review-templates). When an assistant validates or saves a Review Template, the client uploads the YAML file through a short-lived URL instead of putting the template in the model's context.

## Security practices [#security-practices]

* Connect only MCP clients that your organization trusts. The client stores and protects the OAuth token under its own security model.
* Review the tools listed by the client before using them. Enable the client's confirmation or approval controls for actions that create, update, assign, submit, or delete data.
* Use a Clearly AI account with only the access needed for the work.
* Treat instructions contained in project sources, tickets, linked pages, and generated content as untrusted. Do not approve a tool call solely because that content requests it.
* Review the target organization, project, and proposed changes before approving a state-changing tool call.
* Remove the MCP server and its stored authorization from the client when the connection is no longer needed. Follow the client's documentation for its token-removal process.

<Callout type="warn" title="MCP clients act with your permissions">
  A client can request state-changing actions available to your account. Review each consequential tool call and its arguments before approving it.
</Callout>

## Example prompts [#example-prompts]

Start with read-only requests while you verify the connection and the client's approval behavior:

* "Get all the non-compliant answers for the payments-service review."
* "Summarize the open reviews in the checkout-api project."
* "Show me the projects I can access without changing them."
* "Download the security review template as YAML."
* "Validate this review template file without saving it."

## Authentication [#authentication]

The MCP server uses OAuth 2.0. When your AI client first connects to the server, it opens a browser window where you sign in with your existing Clearly AI credentials. After you authenticate, the client stores the token and reuses it for future requests. Clearly AI does not control how a third-party client stores that token.

If your session expires, your client will prompt you to re-authenticate.

<Callout>
  All MCP actions use your identity and respect your Organization permissions. You can only access Projects and Reviews that your account has permission to view or edit.
</Callout>

## Related [#related]

* [API reference](https://docs.clearly-ai.com/docs/api-reference) — REST API for programmatic access
* [CLI](https://docs.clearly-ai.com/docs/cli) — Command-line interface for scripting
* [Reviews](https://docs.clearly-ai.com/docs/reviews) — How reviews work in Clearly AI