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

# MCP Server

> Connect Onset to Claude and other AI assistants to read and write your changelog in natural language.

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

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.

<Info>
  **Server URL:** `https://mcp.onset.io/mcp`
</Info>

## Connect to Claude

<Steps>
  <Step title="Open connector settings">
    In Claude, go to **Settings → Connectors** and click **Add custom connector**.
  </Step>

  <Step title="Add the Onset server">
    Paste `https://mcp.onset.io/mcp` and continue.
  </Step>

  <Step title="Sign in to Onset">
    You'll be redirected to Onset to sign in (or you'll continue with your existing
    session).
  </Step>

  <Step title="Choose a workspace">
    Pick the workspace you want to connect, then click **Authorize**. Access is
    limited to that one workspace.
  </Step>
</Steps>

Once connected, ask Claude 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, fires the
  same [webhooks](/developers/webhooks) as the REST API and dashboard. If your
  workspace has webhook endpoints configured, those requests are sent to your
  external URLs.
</Warning>

## 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 Claude will 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](/developers/api-reference/introduction), 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.
</Note>

## 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.
</Note>

## 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

<AccordionGroup>
  <Accordion title="Claude can't connect to the server">
    Confirm the URL is exactly `https://mcp.onset.io/mcp`. The connection is made
    from Claude's servers, so the endpoint must be reachable from the public
    internet.
  </Accordion>

  <Accordion title="Tools return a workspace error">
    Your connection may point at a workspace you're no longer a member of.
    Remove the connector and add it again, selecting a current workspace.
  </Accordion>

  <Accordion title="Wrong workspace connected">
    Reconnect and pick the workspace you want on the authorization screen. Each
    connection covers exactly one workspace.
  </Accordion>
</AccordionGroup>