# AI Connect (MCP) for developers

> Connect an MCP client to Moknah. Server address, transport, OAuth and bearer token authorization, scopes, plan gates, resources, prompts and the conventions every tool follows.

## Server

| | |
| --- | --- |
| Address | `https://moknah.io/mcp` |
| Transport | Streamable HTTP, stateless, JSON responses |
| Authorization | OAuth 2.1 (authorization code with PKCE), or a bearer token issued by Moknah |
| Acts as | The Moknah user who authorized the connection |

The server is named "Moknah Audio Studio". It exposes tools, resources and prompts.

## Connect

### Clients with connector support

Add a custom connector with the address `https://moknah.io/mcp` and sign in when asked. The client discovers the authorization server by itself and runs the OAuth flow in the browser. The step-by-step screens for each assistant are in the dashboard under **AI Assistant**.

### Bearer tokens

Signing in with OAuth is the way users connect. The server also accepts a fixed bearer token in the `Authorization` header, for integrations that cannot run a browser sign-in. These tokens are not self-service: they are issued by Moknah for a specific account, on request to support@moknah.io. A client that needs a local bridge passes one like this:

```json
{
  "mcpServers": {
    "moknah": {
      "command": "npx",
      "args": ["mcp-remote", "https://moknah.io/mcp", "--header", "Authorization: Bearer YOUR_MCP_TOKEN"]
    }
  }
}
```

Only the hash of a token is stored. A token can be revoked and can carry an expiry date.

## Authorization details

- Discovery: `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`.
- Endpoints: `POST /oauth/register` (dynamic client registration), `/oauth/authorize` (sign-in and consent, PKCE `S256` required), `POST /oauth/token` (`authorization_code` and `refresh_token` grants).
- A request without a valid token is answered `401` with a `WWW-Authenticate` header that points to the protected resource metadata, so a client can start the flow automatically.
- Access tokens are opaque. There is no JWKS and nothing to verify locally.
- An MCP token is not an API key. API keys (`mk_...`) are for the REST API and are not accepted by the MCP server.

## Scopes

An issued token can be limited to groups of tools. A token with no scopes, which is what an OAuth sign-in produces by default, can call every tool.

| Scope | Tools |
| --- | --- |
| `projects` | List, read, create and delete Audio Studio projects |
| `authoring` | Chapters, lines, voice settings, AI review |
| `voices` | List voices and play samples |
| `generation` | Text to speech, rendering, jobs, audio and exports |
| `cost` | Estimates and balance |

A call outside the token's scopes fails with `SCOPE_DENIED`. The documentation tools are not scoped: every token can call them, because they return public information.

## Plan gates

These tools work on every plan: `text_to_speech`, `list_voices`, `play_voice_sample`, `estimate_text_to_speech`, `check_credits`, `get_balance`, `get_job`, `get_job_result`, and all documentation tools.

Every other tool belongs to Audio Studio and needs a plan that includes it. Without one the call fails with `UPGRADE_REQUIRED`, and the error carries the link to the plans page. See [Pricing](../pricing/index.md) for what each plan includes.

## Conventions

### Results and errors

Every tool returns an object with `ok`.

```json
{"ok": true, "project": {"id": 1234, "name": "My book"}}
```

```json
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits for this operation: need 5400, balance 1200 (short 4200).",
    "details": {"required": 5400, "balance": 1200, "shortfall": 4200}
  }
}
```

The error codes are listed in [Errors](../errors/index.md#mcp-tool-errors).

### Spending credits

- Authoring is free: creating projects, editing text, reordering, voice settings and statuses cost nothing.
- Tools that spend credits take `confirm_spend`. Called with `confirm_spend` false they return an estimate and spend nothing. Show the estimate to the user, and call again with `confirm_spend` true only after the user agrees.
- A tool refuses to start work the balance cannot cover.

### Long work

Rendering, document import and AI review run in the background. The tool returns a `job_ref` such as `project:1234`. Poll `get_job` about every 5 seconds until `is_terminal` is true, then call `get_job_result` for the URL of the output.

### Destructive tools

`delete_project`, `delete_chapter` and `delete_line` need an explicit confirmation argument. Ask the user before passing it.

### Access rules

- A tool acts only on the content of the signed-in user and their team.
- Administrator privileges never apply over MCP.
- Every call is recorded and visible to the user in the dashboard.

## Resources

| URI | Content |
| --- | --- |
| `moknah://guide` | The [AI agent guide](../getting-started/ai-agents.md). Start here. |
| `moknah://docs/index` | Index of this documentation. |
| `moknah://docs/<slug>` | One document as Markdown, for example `moknah://docs/api/tts-generate`. Prices and limits are current. |
| `moknah://docs/pricing`, `moknah://docs/limits`, `moknah://docs/errors` | Short forms of the pricing, limits and errors documents. |
| `audio-studio://guide` | Index of the Audio Studio production references. |
| `audio-studio://audiobook-production` | End-to-end document to audiobook workflow. |
| `audio-studio://text-preparation` | Cleaning, verbalization and segmentation of text. |
| `audio-studio://voice-settings` | What every voice parameter does, with safe ranges. |
| `audio-studio://dialogue-and-pacing` | Speaker casting, pauses and line merging. |
| `audio-studio://studio-reference` | Tool mechanics, options, review codes, jobs and limits. |

Documentation resources have the MIME type `text/markdown`.

## Prompts

| Prompt | Purpose |
| --- | --- |
| `get_started_with_moknah` | Find out what Moknah can do for a goal and take the first step. |
| `integrate_text_to_speech` | Integrate text to speech into an application through the API. |
| `narrate_document` | Turn a book or document into a finished audiobook. |
| `debug_api_error` | Diagnose an API, WebSocket or MCP error. |
| `choose_audio_service` | Pick the right service for a task. |
| `review_chapter_qa` | Run AI review on a chapter and walk through the fixes. |
| `set_up_voices` | Pick and apply voices for a project, then estimate the render. |

## Tools

The full list is in [MCP tools](tools.md).
