--- title: "Hoplite MCP server" description: "Delegate work to Hoplite from Claude Code, Cursor, or another MCP client." canonical_url: "https://hoplite.sh/docs/cli/mcp-server" markdown_url: "https://hoplite.sh/docs/cli/mcp-server.md" --- # Hoplite MCP server URL: /docs/cli/mcp-server LLM index: /llms.txt Description: Delegate work to Hoplite from Claude Code, Cursor, or another MCP client. Related: /docs/cli, /docs/agent/mcp, /docs/threads # Hoplite 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 ``` ## Automatic discovery Clients can discover the transport, authentication metadata, and documentation URL from `https://api.hoplite.sh/.well-known/mcp.json`. The same CORS-enabled manifest is available on `https://hoplite.sh/.well-known/mcp.json`, and points to the OAuth protected-resource metadata at `https://api.hoplite.sh/.well-known/oauth-protected-resource/mcp`. The stable `https://hoplite.sh/openapi.json` URL redirects to the reviewed OpenAPI 3.1 specification under `/docs/openapi.json`. The same manifest also advertises API-key authentication, alongside the OAuth metadata that OAuth-only clients keep reading. ## Choose how to authenticate The server accepts two credentials on every request, and you pick one per client: - **OAuth** is the default for interactive clients. Your MCP client opens a browser the first time it connects, you sign in and pick a workspace, and the client refreshes the token for you. Calls act as you, so every tool and API route that needs a signed-in user works. Prefer OAuth whenever a person sits at the client. - **API keys** (`hop_…`) suit CI jobs, headless agents, and shared machines where nobody can complete a browser sign-in. The key fixes the workspace, and its permissions decide what the client can do. Service-account keys (`hop_svc_…`) also keep their project restrictions. Routes that only make sense for a signed-in user, such as personal skills or onboarding, return a 403 that asks you to connect with OAuth. ## Set it up with OAuth For 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. For clients configured with an `mcpServers` map: ```json title="mcp config" { "mcpServers": { "hoplite": { "type": "http", "url": "https://api.hoplite.sh/mcp" } } } ``` ### Authorize ahead of time You can also run the authorization from a terminal before any client connects, which helps with scripted setups: ```bash title="terminal" hoplite mcp start ``` This opens the browser OAuth flow and stores the token locally (`~/.config/hoplite/mcp-oauth.json`). If you don't have the [CLI](/docs/cli) installed, `npx -y @usehoplite/cli mcp start` works too. ## API keys Create a key under **Settings → Workspace → API keys**, or create a [service account](/docs/workspace#api-keys) for unattended integrations. Give it the permissions the tools need: project read for `hoplite_list_projects`, thread read for listing and fetching threads, and thread create for `hoplite_create_thread`. Send the key in either header: ```http Authorization: Bearer hop_... ``` ```http X-Api-Key: hop_... ``` Keep the key in an environment variable rather than pasting it into commands or config files. For Claude Code, the shell expands the variable when you add the server: ```bash title="terminal" export HOPLITE_API_KEY="hop_..." claude mcp add --transport http hoplite https://api.hoplite.sh/mcp --header "Authorization: Bearer $HOPLITE_API_KEY" ``` For clients configured with an `mcpServers` map, add a `headers` entry. Claude Code's `.mcp.json` expands `${HOPLITE_API_KEY}` at startup; if your client doesn't expand variables, put the key itself there and keep the file out of version control: ```json title="mcp config" { "mcpServers": { "hoplite": { "type": "http", "url": "https://api.hoplite.sh/mcp", "headers": { "Authorization": "Bearer ${HOPLITE_API_KEY}" } } } } ``` The CLI prints either form for you. `hoplite mcp config` prints the JSON entry, `hoplite mcp config --format claude` prints the `claude mcp add` command, and `hoplite mcp config --inline-key` embeds the key the CLI resolves (from `--api-key`, `HOPLITE_API_KEY`, or stored credentials) after checking that it's still valid. An invalid, revoked, or expired key gets a `401` with the message `Invalid or revoked API key.` A key calling a route its permissions don't cover gets a `403` tool error that says the key lacks permission for that operation. ## 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` (or `modelId`), title, and idempotency key | | `hoplite_call_api` | Call reviewed Hoplite API routes as the authorized user or API key — inspect workspace, project, repository, model, thread, run, pull-request, automation, preview, billing, and usage state; manage the write families below | Pass `model` to `hoplite_create_thread` when a run should not inherit the project's default. `modelId` is a backwards-compatible alias; when both are supplied they must match. The value must be a supported Hoplite model ID, such as `claude-sonnet-5` or `gpt-6-sol`. 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 reviewed write surface includes project CRUD and repository assignment; project environment variables and prebuild rebakes; automation CRUD and runs; thread creation, updates, deletion, messages, attachment staging and confirmation, stop/retry/compact actions, approvals, and checkpoint restores; pull-request creation, merge, and review-loop settings; preview start and checklist updates; and selected organization settings, imports, feedback, onboarding, and waitlist writes. Through `hoplite_call_api`, `POST /api/threads/{id}/messages` accepts `metadata.model` as a supported Hoplite model ID to select that message run's model, and `POST /api/threads/{id}/stop` accepts an optional `runId` and targets the active run when it is omitted. `hoplite_call_api` limits each response body to 1 MiB. If a diff or export exceeds that limit, it returns `api_response_too_large`; request a smaller page where supported, or retrieve the resource through the REST API. The MCP server does not expose existing credential retrieval or rotation, terminal sessions, browser controls, binary attachment transfer, or raw workspace logs. Creation endpoints can return caller-owned one-time credentials, such as a new webhook automation's token, and attachment staging returns the short-lived upload URL needed to complete that transaction. This page is about driving Hoplite from your tools. To give the Hoplite agent extra tools from MCP servers you host or run, see [MCP servers](/docs/agent/mcp). ## Sitemap Sitemap discovery is not enabled for this deployment.