# MCP server

> Let a local agent search the catalog, read node docs, validate Toys and edit your drafts.

Source: https://docs.tune.toys/developers/mcp/ (updated 2026-11-01)

**Status:** Implemented as a private stdio package, not yet published to npm. A hosted remote endpoint needs OAuth for users and is planned.

`@tunetoys/mcp` is a Model Context Protocol server. It is an ordinary API client: every call goes through the SDK with your developer key, so it gets exactly that key's scopes, limits and owner checks.

## Configuration

| Variable            | Default                | Meaning                                                     |
| ------------------- | ---------------------- | ----------------------------------------------------------- |
| `TUNETOYS_API_KEY`  | none                   | Developer key. Without it only anonymous read tools appear. |
| `TUNETOYS_API_BASE` | `https://tune.toys/v1` | API base, for example a local API                           |

```sh
claude mcp add tunetoys --env TUNETOYS_API_KEY=tt_... -- node /path/to/TuneToys/packages/mcp/src/main.ts
```

Keep the key in the client's secret configuration, never in a repository.

## Tools

| Tool                                           | Needs                   | Behavior                                             |
| ---------------------------------------------- | ----------------------- | ---------------------------------------------------- |
| `search_catalog`, `get_listing`, `get_product` | none                    | Public reads                                         |
| `get_node_docs`                                | none                    | Node contract and docs, local                        |
| `validate_toy_json`                            | none                    | Validates against the Toy schema, local              |
| `get_toy_source`                               | none or `read:projects` | A release by digest, or your draft                   |
| `list_my_projects`                             | `read:projects`         | Your drafts                                          |
| `propose_operations`                           | `read:projects`         | Applies a batch locally and reports; writes nothing  |
| `create_draft_project`, `apply_operations`     | `write:projects`        | Creates a draft; applies revision-checked operations |
| `update_listing_fields`                        | `write:listings`        | Saves listing overrides; does not publish            |

## Safety

Write tools carry `destructiveHint`, accept at most 64 operations per batch and share a budget of 20 write calls per process. Conflicts surface as tool errors; the agent must re-read and propose again. No tool publishes, changes visibility, uploads media or touches billing.