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

# Install the MCP server

> Give your coding agent live tool access to the Alakazam /v1 API via the Model Context Protocol.

The Alakazam MCP server exposes the `/v1` API as **tools your agent can call directly** — generate worlds, edit graphs, create characters, mint embed sessions — and see real responses, without you writing fetch code. It pairs with the [skill](/install-skill): the skill teaches *when* to use the API, the MCP server *executes* it.

It's a small stdio server ([`@alakazamworld/mcp`](https://www.npmjs.com/package/@alakazamworld/mcp)) that reads your secret key and proxies to `https://api.alakazam.gg`.

## Prerequisites

* An Alakazam **secret key**. Create an app at [play.alakazam.gg/?view=developer](https://play.alakazam.gg/?view=developer) and mint one. Use an **`sk_test_…`** key while wiring things up — it hits the free, mocked [sandbox](/testing) (no GPU spend).
* **Node.js 18+** (the server runs via `npx`).

## The tools

| Tool                                   | Does                                                           |
| -------------------------------------- | -------------------------------------------------------------- |
| `create_world`                         | Generate a world from a premise/image (or `async` + `get_job`) |
| `get_world` · `list_worlds`            | Read your worlds                                               |
| `edit_world`                           | Natural-language graph edit (kernel-validated)                 |
| `fork_world`                           | Clone a world into a new private one                           |
| `create_character` · `list_characters` | Create + list talk-to characters                               |
| `mint_session`                         | Mint a session token to embed a world (two-token rule)         |
| `get_usage`                            | Today's usage vs caps                                          |

## Install

Add the server to your agent with your key in the env. The config is identical everywhere — `npx -y @alakazamworld/mcp` with `ALAKAZAM_SECRET_KEY`:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add alakazam --env ALAKAZAM_SECRET_KEY=sk_test_... -- npx -y @alakazamworld/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

    ```json theme={null}
    {
      "mcpServers": {
        "alakazam": {
          "command": "npx",
          "args": ["-y", "@alakazamworld/mcp"],
          "env": { "ALAKAZAM_SECRET_KEY": "sk_test_..." }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "alakazam": {
          "command": "npx",
          "args": ["-y", "@alakazamworld/mcp"],
          "env": { "ALAKAZAM_SECRET_KEY": "sk_test_..." }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex CLI">
    Add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.alakazam]
    command = "npx"
    args = ["-y", "@alakazamworld/mcp"]
    env = { ALAKAZAM_SECRET_KEY = "sk_test_..." }
    ```
  </Tab>
</Tabs>

<Note>
  Prefer not to inline the key? Omit the `env` block and export `ALAKAZAM_SECRET_KEY`
  in the shell your agent inherits — the server reads it from the environment.
</Note>

## Verify

Restart your agent and ask:

> "Using the Alakazam MCP, create a test world from the premise 'a quiet observatory at dusk' and show me the response."

With an `sk_test_…` key you'll get back a world marked `"mock": true` (a free sandbox response) — that confirms the tool call reached the API and came back. Ask it to `get_usage` to see your live caps.

## Next steps

<CardGroup cols={2}>
  <Card title="Install the skill" icon="wrench" href="/install-skill">
    Teach the agent *when* to reach for each tool.
  </Card>

  <Card title="Agent quickstart" icon="robot" href="/agent-quickstart">
    One-paste onboarding + repo scan.
  </Card>

  <Card title="Embedding" icon="square-code" href="/embedding">
    Take a minted session token to the browser.
  </Card>

  <Card title="Testing sandbox" icon="flask" href="/testing">
    Build the whole thing free with a test key.
  </Card>
</CardGroup>