# PatchHub MCP server

URL: `https://patchhub.sh/mcp`

Transport: Streamable HTTP. POST JSON-RPC, JSON responses, stateless (no session ID). Protocol version `2025-06-18`.

## Install

### Claude Code

```sh
claude mcp add --transport http patchhub https://patchhub.sh/mcp
```

With a token instead of OAuth:

```sh
claude mcp add --transport http patchhub https://patchhub.sh/mcp --header "Authorization: Bearer phg_…"
```

### Cursor

`.cursor/mcp.json`:

```json
{ "mcpServers": { "patchhub": { "url": "https://patchhub.sh/mcp" } } }
```

With a token, add `"headers": { "Authorization": "Bearer phg_…" }`.

### Other clients

Point any client that supports remote (HTTP) MCP servers at `https://patchhub.sh/mcp`.

If it can't do OAuth, send `Authorization: Bearer <token>` (create one at https://patchhub.sh/settings).

## How sign-in works

PatchHub supports MCP OAuth 2.1.

Your client finds the authorization server through `https://patchhub.sh/.well-known/oauth-protected-resource`.

It opens a PatchHub page where you sign in and approve the client.

The client receives a normal PatchHub access token. It shows up in https://patchhub.sh/settings and you can revoke it there.

## Tools

Every tool accepts an optional `intent`: the person's goal in their own words. Always set it. Never put secrets in it.

| Tool | Arguments | What it does |
|---|---|---|
| `get_started` | | How PatchHub works and what to do first. Call this first. |
| `list_projects` | `owner?`, `query?` | Find projects. |
| `get_project` | `project`, `include_readme?` | Details, download variants and README. |
| `create_project` | `name`, `description?`, `private?` | New empty project you maintain. |
| `list_files` | `project` | File paths in the main version. |
| `read_file` | `project`, `path` | One file's content. |
| `list_patches` | `project`, `status?` | Patches, ranked by popularity. `status`: published, merged, draft. |
| `get_patch` | `patch_id`, `include_diff?` | Conversation, AI summary and optionally the diff. |
| `create_patch` | `project`, `message` | The AI makes a change. Returns a `job_id`. |
| `send_patch_message` | `patch_id`, `message` | Refine your draft. Returns a `job_id`. |
| `publish_patch` | `patch_id` | Safety check, description, publish. Returns a `job_id`. |
| `merge_patch` | `patch_id` | Maintainer: add it to the main version. Returns a `job_id`. |
| `vote_patch` | `patch_id`, `vote` | Upvote (`true`) or remove your vote (`false`). |
| `wait_for_job` | `job_id`, `wait_seconds?` | Waits up to 55 s (default 50) for a job. Call again until `done`. |
| `list_versions` | `project` | Versiond versions. |
| `create_version` | `project`, `name`, `notes?` | Maintainer: version the current main version. |
| `download` | `project`, `version?`, `variant?`, `patches?` | A download link, or a build to wait for. |
| `star_project` | `project`, `star?` | Star (default) or unstar a project. Counts are public; who starred is private. |
| `list_starred` | none | Projects you starred (private to you). |
| `list_commits` | `project`, `limit?`, `skip?` | Commit history of main, newest first. |
| `get_commit` | `project`, `sha` | One commit's message and diff. |
| `get_download` | `download_id` | Build status and `download_url`. |
| `create_upload` | `project` | Maintainers: get a `put_url` to PUT a .zip of a new main version to. |
| `upload_version` | `project`, `upload_id`, `note?` | Maintainers: make the uploaded zip the new main version. |
| `send_feedback` | `kind`, `message`, `request_id?` | Report a real problem once. |

## Results

Each result is JSON text with `data` and `next`.

`next` lists your next steps in plain English.

When a call fails, the result has `isError: true` and contains the error object (`code`, `message`, `hint`).

Error codes are listed in https://patchhub.sh/docs/api.md#errors.

## Things to ask your agent

- "Find the snake game on PatchHub and give me a version with the neon theme and wrap-around walls."
- "Add a dark mode to patchhub/notes and download it for me."
- "Start a PatchHub project for this folder and push it."
- "Which patches for my project are the most popular? Merge the safe ones."
- "Download patchhub/tasks for my Mac."

The full agent guide: https://patchhub.sh/AGENTS.md