---
title: "MCP server"
description: "Drive Hoplite from Claude Code, Cursor, or any MCP client"
canonical_url: "https://hoplite.sh/docs/mcp-server"
markdown_url: "https://hoplite.sh/docs/mcp-server.md"
---

# MCP server
URL: /docs/mcp-server
LLM index: /llms.txt
Description: Drive Hoplite from Claude Code, Cursor, or any MCP client
Related: /docs/cli, /docs/integrations/mcp, /docs/threads

# MCP server

Hoplite exposes its own [Model Context Protocol](https://modelcontextprotocol.io) server, so the agent you're already talking to — Claude Code, Cursor, or any MCP client — can list your projects, start Hoplite threads, and call the API. "Have Hoplite fix the flaky auth test" becomes a single tool call.

The server runs over streamable HTTP at:

```text
https://api.hoplite.sh/mcp
```

Authentication is OAuth: on first connect, your MCP client opens a browser where you sign in and authorize a workspace. Clients that support MCP OAuth (Claude Code, and most current clients) handle the whole flow automatically.

## Set it up

<Tabs items={["Claude Code", "JSON config"]}>
  <Tab value="Claude Code">
    ```bash title="terminal"
    claude mcp add --transport http hoplite https://api.hoplite.sh/mcp
    ```

    The first tool call triggers the browser sign-in.
  </Tab>
  <Tab value="JSON config">
    For clients configured with an `mcpServers` map:

    ```json title="mcp config"
    {
      "mcpServers": {
        "hoplite": {
          "type": "http",
          "url": "https://api.hoplite.sh/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

You can also run the authorization ahead of time from a terminal — useful for scripted setups:

```bash title="terminal"
npx -y @usehoplite/cli mcp start
```

This opens the browser OAuth flow and stores the token locally (`~/.config/hoplite/mcp-oauth.json`).

## What you get

| Tool | What it does |
| --- | --- |
| `hoplite_list_projects` | List projects in the authorized workspace |
| `hoplite_list_threads` | List threads, filterable by project and status |
| `hoplite_get_thread` | Fetch one thread |
| `hoplite_create_thread` | **Start an agent run** — takes a project id and prompt, plus optional `model`, title, and idempotency key |
| `hoplite_call_api` | Call reviewed Hoplite API routes with the authorized session — inspect models, repositories, thread timelines and tool calls; manage projects and thread actions |

Pass `model` to `hoplite_create_thread` when a run should not inherit the project's default. The value must be a supported Hoplite model ID, such as `claude-sonnet-4-6` or `gpt-5.6-terra`.

Use `hoplite_call_api` with `GET /api/model-providers` to inspect the current model catalog and its reasoning/speed capabilities before creating a thread. GitHub discovery is available through `GET /api/github/installations` to determine whether the workspace is connected, followed by `GET /api/github/repositories` and `GET /api/github/repositories/:id/branches` to select a repository and branch.

The MCP server intentionally does not return credentials, terminal/browser session URLs, or raw workspace logs. Use the web app for those sensitive operations.

<Callout type="info" title="The other direction">
This page is about driving Hoplite from your tools. To give the Hoplite agent extra tools from MCP servers you host or run, see [Integrations → MCP servers](/docs/integrations/mcp).
</Callout>

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).