---
title: "LyricWinter MCP server: connect Claude, ChatGPT, Cursor, and other agents"
description: "Connect any MCP client to the remote LyricWinter Studio MCP server at https://lyricwinter.com/mcp using Streamable HTTP with OAuth 2.1 or a scoped API key."
canonical_url: https://lyricwinter.com/docs/mcp
markdown_url: https://lyricwinter.com/docs/mcp.md
last_updated: 2026-09-30
status: beta
---
# LyricWinter MCP server: connect Claude, ChatGPT, Cursor, and other agents

> Connect any MCP client to the remote LyricWinter Studio MCP server at https://lyricwinter.com/mcp using Streamable HTTP with OAuth 2.1 or a scoped API key.

The LyricWinter MCP server lets AI agents work in LyricWinter Studio on your behalf. Connect any Model Context Protocol client to `https://lyricwinter.com/mcp` and the agent can list your projects, read story documents, create stories, generate multi-voice audio, and follow workflow progress. The server uses the Streamable HTTP transport and authenticates with OAuth 2.1 or a Studio-scoped API key.

| Property | Value |
| --- | --- |
| Server URL | `https://lyricwinter.com/mcp` |
| Transport | Streamable HTTP |
| Authentication | OAuth 2.1 with PKCE, or `Authorization: Bearer lw_...` |
| Scopes | `studio:read` (required), `studio:write` (to create stories and audio) |
| Tools | [13 Studio tools](/docs/mcp-tools) |
| Status | Beta |

## Connect Claude

**Claude on the web and Claude Desktop.** Open **Settings → Connectors**, choose **Add custom connector**, and enter `https://lyricwinter.com/mcp`. Claude opens LyricWinter so you can sign in and approve access.

**Claude Code.** Add the server, then run `/mcp` inside Claude Code and choose **Authenticate**:

```bash
claude mcp add --transport http lyricwinter https://lyricwinter.com/mcp
```

## Connect ChatGPT

In ChatGPT, turn on developer mode for apps and connectors, then create a connector with the URL `https://lyricwinter.com/mcp` and OAuth authentication. ChatGPT sends you to LyricWinter to sign in and approve access. Refresh the connector after LyricWinter adds new tools.

## Connect VS Code

Add the server to `.vscode/mcp.json` in your workspace, or to your user MCP configuration. VS Code prompts you to sign in when the server starts.

```json title=".vscode/mcp.json"
{
  "servers": {
    "lyricwinter": {
      "type": "http",
      "url": "https://lyricwinter.com/mcp"
    }
  }
}
```

## Connect Cursor

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project). Use a Studio-scoped [API key](/docs/authentication) in the `Authorization` header:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "lyricwinter": {
      "url": "https://lyricwinter.com/mcp",
      "headers": {
        "Authorization": "Bearer lw_..."
      }
    }
  }
}
```

## Connect Codex

Add the server to `~/.codex/config.toml`, then sign in:

```toml title="~/.codex/config.toml"
[mcp_servers.lyricwinter]
url = "https://lyricwinter.com/mcp"
```

```bash
codex mcp login lyricwinter
```

## Connect other MCP clients

Any client that supports remote MCP servers over Streamable HTTP can connect:

1. Point the client at `https://lyricwinter.com/mcp`.
2. If the client supports MCP authorization, it discovers LyricWinter's OAuth server from the `WWW-Authenticate` challenge and the protected-resource metadata at `https://lyricwinter.com/.well-known/oauth-protected-resource/mcp`, registers itself, and opens the LyricWinter sign-in page.
3. Otherwise, send a Studio-scoped API key as `Authorization: Bearer lw_...`.

To test the server by hand, run the MCP Inspector and connect it to the same URL:

```bash
npx @modelcontextprotocol/inspector
```

## How does MCP authentication work?

LyricWinter hosts its own OAuth 2.1 authorization server for the MCP server:

1. An unauthenticated request returns `401` with a `WWW-Authenticate` header that points to the protected-resource metadata.
2. The client registers through dynamic client registration (`/oauth/register`) and starts the authorization code flow with PKCE (`S256`).
3. You sign in to LyricWinter and approve `studio:read` and, if the client asks for it, `studio:write`.
4. LyricWinter issues a one-hour access token and a 30-day refresh token that rotates on every use.

Each token only reaches the account that approved it. To disconnect a client, revoke its key in the **Developers** panel of your [dashboard](/dashboard). See [Authentication](/docs/authentication#how-do-mcp-clients-authenticate) for endpoints and supported parameters.

Clients that cannot complete OAuth can send a LyricWinter API key with the `studio:read` and `studio:write` scopes instead.

## What can I ask an agent to do?

Once connected, ask in plain language. For example:

- "Show my LyricWinter Studio projects."
- "Create a Studio story called *The Lighthouse* from this text and prepare it for audio."
- "Add this chapter to my *Winter Road* project."
- "Generate audio for chapters 1 through 3 and tell me when it's done."
- "Which characters speak in this project, and how often?"

The agent picks the right [tools](/docs/mcp-tools) and polls workflows until they finish. The tool descriptions tell agents to confirm with you before starting paid audio generation.

## Does the MCP server cost anything?

Connecting and reading are free. `start_audio_workflow` runs Create Audio, which consumes words from your LyricWinter balance exactly as it does in the Studio app. The tool is marked as having side effects so that clients ask for confirmation, and its description tells agents to confirm scope and cost with you first.

## What the MCP server does not do yet

The beta MCP server covers the core story-to-audio loop. These tasks are available in the [REST API](/docs/api) and the [Studio app](/studio) but not yet as MCP tools:

- Editing document blocks and recasting speakers
- Exports to MP3, WAV, M4B, EPUB, or SRT
- Public share links
- Uploading sounds or custom voices

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| The client says authorization is required or expired | Reconnect or re-authenticate the server in your client. Access tokens last one hour and refresh automatically when the client supports it. |
| A tool returns "lacks Studio access" | The token or API key is missing `studio:read` or `studio:write`. Reconnect and approve both, or use a key with both scopes. |
| `403 Origin is not allowed` | Browser-based clients must connect from `lyricwinter.com` or `chatgpt.com`. Use a desktop, CLI, or server-side client instead. |
| A write tool timed out | The result includes a `mutation_id`. Call the tool again with the same `mutation_id` to retry safely without creating a duplicate or a second paid run. |