---
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-10-02
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 turn a story into fully cast audio, play it, share it, change character voices, add your own voice, and work with your Studio projects. In ChatGPT, Claude, and other apps that support interactive MCP Apps, a story player and a voice panel appear right in the conversation. 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), `voices:read` and `voices:write` (to recast characters and add your voice) |
| Tools | [22 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 them, `studio:write`, `voices:read`, and `voices: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, plus `voices:read` and `voices:write` for the voice tools.

## What can I ask an agent to do?

Once connected, ask in plain language. For example:

- "Read this chapter aloud with a different voice for each character."
- "Turn my fanfic into an audio drama." (paste the story)
- "Give Mara a raspier, older voice."
- "I want to narrate it in my own voice."
- "Make a link I can share."
- "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, and new LyricWinter accounts include free words. `create_audio_story`, `recast_character`, and `start_audio_workflow` run Create Audio, which consumes words from your LyricWinter balance exactly as it does in the Studio app. These tools are marked as having side effects so that clients can ask for confirmation.

## 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, or directing a specific line ("whisper this")
- Exports to WAV, M4B, EPUB, or SRT
- Uploading sounds or voice model files

## 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 this permission" | The token or API key is missing a scope the tool needs. Reconnect LyricWinter and approve access, or use a key with the listed 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. |