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

# MCP Server

> Connect Onset to Claude, Cursor, VS Code, Codex and other AI clients to read and write your changelog in natural language.

The Onset MCP server lets AI assistants and coding agents work with your changelog
directly: listing releases, drafting and publishing new ones, and managing
subscribers, without leaving the chat or your editor.

It implements the [Model Context Protocol](https://modelcontextprotocol.io) over
Streamable HTTP, and authenticates with OAuth 2.1, so you sign in with your normal
Onset account. No API key required.

> [!NOTE]
>
> **Server URL:** `https://mcp.onset.io/mcp`

## Connect your client

Any client that supports remote MCP servers over Streamable HTTP with OAuth can
connect. Point it at `https://mcp.onset.io/mcp` — there's no API key to paste.

> [tab] Claude
>
> **1. Find Onset in the directory**
>
> Open the [Onset listing](https://claude.ai/directory/onset) in the Claude
> connector directory, or search for **Onset** under **Settings → Connectors**.
>
> **2. Connect**
>
> Click **Connect**.
>
> **3. Sign in to Onset**
>
> You'll be redirected to Onset to sign in (or you'll continue with your existing
> session).
>
> **4. Choose a workspace**
>
> Pick the workspace you want to connect, then click **Authorize**. Access is
> limited to that one workspace.
>
> > [!TIP]
> >
> > You can also add it by URL: **Settings → Connectors → Add custom connector**,
> > then paste `https://mcp.onset.io/mcp`.

> [tab] Claude Code
>
> Add the server from your terminal:
>
> ```bash theme={null}
> claude mcp add --transport http onset https://mcp.onset.io/mcp
> ```
>
> Then run `/mcp` inside Claude Code, pick **onset**, and complete the sign-in
> and workspace selection in your browser. Tokens are stored and refreshed for
> you; use **Clear authentication** in the `/mcp` menu to revoke access.
>
> Add `--scope project` to share the server with your team through a checked-in
> `.mcp.json`, or `--scope user` to make it available in every project.

> [tab] Cursor
>
> Add Onset to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project only):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "onset": {
>       "url": "https://mcp.onset.io/mcp"
>     }
>   }
> }
> ```
>
> Open **Settings → Features → Model Context Protocol**. Cursor discovers the
> Onset authorization server automatically, registers itself, and opens your
> browser so you can sign in and pick a workspace.

> [tab] VS Code
>
> Add Onset to `.vscode/mcp.json` in your project:
>
> ```json theme={null}
> {
>   "servers": {
>     "onset": {
>       "type": "http",
>       "url": "https://mcp.onset.io/mcp"
>     }
>   }
> }
> ```
>
> Or run **MCP: Add Server** from the Command Palette and choose **HTTP**, which
> writes the same entry. To make Onset available everywhere instead of one
> project, use **MCP: Open User Configuration**.
>
> On first use, VS Code opens a browser window for the OAuth flow. Start the
> server with **MCP: List Servers → onset → Start** if it hasn't connected yet.

> [tab] Codex
>
> Add the server from your terminal:
>
> ```bash theme={null}
> codex mcp add onset --url https://mcp.onset.io/mcp
> codex mcp login onset
> ```
>
> Or edit `~/.codex/config.toml` directly:
>
> ```toml theme={null}
> [mcp_servers.onset]
> url = "https://mcp.onset.io/mcp"
> ```
>
> `codex mcp login onset` opens your browser for the OAuth flow. Run `/mcp` in
> the Codex TUI to confirm the server is connected. The CLI and the IDE
> extension share this config, so you only set it up once.

Once connected, ask things like *"What did we ship last month?"* or
*"Draft a release for version 2.1 from these notes."*

## Workspace access

Each connection is scoped to a **single workspace**, chosen at the moment you
authorize. The workspace is bound into the access token, and every request is
re-checked against your current membership, so if you're removed from a
workspace, the connection stops working immediately.

To connect a different workspace, authorize again and select it. Each workspace
is granted separately.

Anyone who can access a workspace through the Onset API can use these tools for
that workspace.

## Available tools

### Releases

| Tool | Description |
| - | - |
| `list_releases` | List releases, optionally filtered by status, project, or labels |
| `get_release` | Get a single release by id or number |
| `create_release` | Create a new release as a **draft** |
| `update_release` | Update the content of an existing release |
| `publish_release` | Publish a release now, schedule it, or reschedule it |

### Projects, labels & contributors

| Tool | Description |
| - | - |
| `list_projects` | List projects in the workspace |
| `list_labels` | List labels in the workspace |
| `list_contributors` | List workspace members available as contributors |

### Subscribers

| Tool | Description |
| - | - |
| `list_subscribers` | List changelog subscribers |
| `list_subscriber_lists` | List subscriber lists |
| `create_subscriber` | Add a subscriber, optionally to specific lists |

Read tools can run without confirmation. Tools that create or change data will
ask you to confirm before running.

> [!WARNING]
>
> Creating, updating or publishing a release, and adding a subscriber, fire the
> same [webhooks](https://onset.io/docs/developers/webhooks.md) as the REST API and dashboard. If your
> workspace has webhook endpoints configured, those requests are sent to your
> external URLs.

## Drafts and publishing

`create_release` always creates a **draft**. Nothing appears on your changelog
until it's published, so you can let an assistant write a release and review it
before anyone sees it.

Publishing is a separate, explicit step (`publish_release`), and most clients ask
you to confirm before running it. You can publish immediately (`RELEASED`) or
schedule it for a future date (`SCHEDULED`, available on plans that include
scheduled releases).

The same tool works on a release that's already scheduled, so you can ask to
publish it early or move it to a different date. Once a release is live, use
`update_release` to change its content.

This mirrors the [REST API](https://onset.io/docs/developers/api-reference/introduction.md), where
releases are also created as drafts and published through a separate endpoint.

> [!NOTE]
>
> **Notifications are never sent over MCP.** Publishing through an AI assistant
> does not send subscriber emails or Slack and Discord messages. To notify people,
> publish from the Onset dashboard, where you choose the channels.

## Prompts and resources

Alongside tools, the server exposes:

* **`draft_release_notes`** is a prompt that turns a list of changes into
  structured release notes. Provide your highlights plus an optional version and
  tone.
* **`onset://releases/{id}`** exposes your releases as readable Markdown, so clients
  that support resources can pull a release into context directly.

> [!NOTE]
>
> Support for prompts and resources varies by AI client. All clients support tools.

## Plan limits

MCP requests count toward the same plan limits as the REST API. For example,
adding a subscriber fails once you reach your plan's subscriber limit.

## Troubleshooting

> [accordion] The client can't connect to the server
>
> Confirm the URL is exactly `https://mcp.onset.io/mcp`. Web clients like Claude
> connect from their own servers, so the endpoint must be reachable from the
> public internet.

> [accordion] The sign-in window never opens
>
> Some clients don't start the OAuth flow until the server is running. In VS Code
> use **MCP: List Servers → onset → Start**, in Claude Code run `/mcp`, and in
> Codex run `codex mcp login onset`.

> [accordion] Tools return a workspace error
>
> Your connection may point at a workspace you're no longer a member of.
> Remove the server and add it again, selecting a current workspace.

> [accordion] Wrong workspace connected
>
> Reconnect and pick the workspace you want on the authorization screen. Each
> connection covers exactly one workspace.

> [accordion] Tools don't show up after connecting
>
> Restart the server or reload the client. In VS Code, run **MCP: Reset Cached
> Tools**. In Cursor, check **Output → MCP Logs** for connection errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.