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

# Client setup

> One endpoint, eight clients. Pick yours.

Every client uses the same URL:

```text theme={null}
https://www.ninjachat.ai/api/mcp
```

Claude and ChatGPT use OAuth. For editors and CLIs, create a connection key in [Developers → Agents](https://www.ninjachat.ai/developers/agents). Replace the entire `nj_sk_YOUR_KEY` placeholder with your key. Merge these entries into existing configuration; keep your other servers. Use HTTP, not SSE.

<AccordionGroup>
  <Accordion title="Claude (claude.ai)" icon="comments">
    **Settings → Connectors → Add custom connector.** Name it `NinjaChat`, paste the URL, and sign in. Enable NinjaChat in each chat or project where you want to use it. Your account or workspace must allow custom connectors.
  </Accordion>

  <Accordion title="ChatGPT" icon="comment-dots">
    **Settings → Security and login → Developer mode**, then [Plugins](https://chatgpt.com/plugins) → **+**. Name it `NinjaChat`, paste the endpoint under **Connection**, and sign in. Add it from the tools menu in a new chat. Availability depends on your account and workspace. [Official guide](https://developers.openai.com/plugins/deploy/connect-chatgpt).
  </Accordion>

  <Accordion title="Cursor" icon="code">
    ```json ~/.cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "ninjachat": {
          "url": "https://www.ninjachat.ai/api/mcp",
          "headers": {
            "Authorization": "Bearer nj_sk_YOUR_KEY"
          }
        }
      }
    }
    ```

    **Cursor Settings → MCP** should show `ninjachat` with a green dot. If not, reload the window.
  </Accordion>

  <Accordion title="Claude Code" icon="terminal">
    ```bash theme={null}
    claude mcp add --transport http --scope user ninjachat https://www.ninjachat.ai/api/mcp --header "Authorization: Bearer nj_sk_YOUR_KEY"
    ```

    Verify with `/mcp` inside Claude Code. For one project, use `--scope local` and run from that project folder. Keep `--header` after the server name and URL. [Official guide](https://code.claude.com/docs/en/mcp).

    <Note>
      Listed as failed? Use `--transport http` (not `sse`) and keep the whole `"Authorization: Bearer …"` string as one shell argument.
    </Note>
  </Accordion>

  <Accordion title="Codex" icon="square-code">
    ```toml ~/.codex/config.toml theme={null}
    [mcp_servers.ninjachat]
    url = "https://www.ninjachat.ai/api/mcp"
    http_headers = { "Authorization" = "Bearer nj_sk_YOUR_KEY" }
    startup_timeout_sec = 30
    tool_timeout_sec = 180
    ```

    Start a new Codex session after saving. [Official MCP configuration](https://developers.openai.com/codex/mcp).

    <Note>
      TOML is picky: `[mcp_servers.ninjachat]` with an underscore, and `http_headers` as an inline table.
    </Note>
  </Accordion>

  <Accordion title="VS Code" icon="window">
    ```json .vscode/mcp.json theme={null}
    {
      "inputs": [{ "type": "promptString", "id": "ninjachat-key", "description": "NinjaChat API key", "password": true }],
      "servers": {
        "ninjachat": {
          "type": "http",
          "url": "https://www.ninjachat.ai/api/mcp",
          "headers": { "Authorization": "Bearer ${input:ninjachat-key}" }
        }
      }
    }
    ```

    Click **Start** above the entry, enter your key when prompted, then enable NinjaChat in Copilot Chat agent mode. Keep the `${input:ninjachat-key}` variable as written.
  </Accordion>

  <Accordion title="Hermes" icon="wave-sine">
    ```yaml ~/.hermes/config.yaml theme={null}
    mcp_servers:
      ninjachat:
        url: "https://www.ninjachat.ai/api/mcp"
        headers:
          Authorization: "Bearer nj_sk_YOUR_KEY"
        enabled: true
    ```

    Start a new session — the dashboard's MCP panel shows the connection.
  </Accordion>

  <Accordion title="OpenClaw" icon="robot">
    ```bash theme={null}
    openclaw mcp add ninjachat --url https://www.ninjachat.ai/api/mcp --transport streamable-http --header "Authorization=Bearer nj_sk_YOUR_KEY"
    ```

    Run `openclaw mcp probe ninjachat`, then start a new agent session. OpenClaw headers use `KEY=VALUE`; the equals sign is required.
  </Accordion>
</AccordionGroup>

Review or disconnect OAuth agents anytime in [Developers → Agents](https://www.ninjachat.ai/developers/agents).

## Building your own OAuth client

NinjaChat is a full OAuth 2.1 authorization server, so any MCP client that speaks the standard flow connects without an API key:

* **Discovery.** An unauthenticated request to the endpoint returns `401` with a `WWW-Authenticate` challenge pointing at `https://www.ninjachat.ai/.well-known/oauth-protected-resource/api/mcp`; the authorization-server metadata is at `https://www.ninjachat.ai/.well-known/oauth-authorization-server`.
* **Registration.** Open Dynamic Client Registration at `https://www.ninjachat.ai/api/oauth/register`. Clients are public — there is no client secret — and the `redirect_uri` you authorize with must be one you registered. A client unused for 90 days is garbage-collected.
* **Authorization.** `https://www.ninjachat.ai/oauth/authorize` with `code_challenge_method=S256`. PKCE is mandatory and `plain` is rejected; authorization codes expire after 60 seconds. The only scope is `mcp`.
* **Tokens.** `https://www.ninjachat.ai/api/oauth/token` supports `authorization_code` and `refresh_token`. Access tokens (`nj_at_…`) last **1 hour**; refresh tokens (`nj_rt_…`) last **30 days** and **rotate on every use** — replaying a rotated refresh token revokes the whole token family. Revoke either token at `https://www.ninjachat.ai/api/oauth/revoke`.

## Test it

Free, and proves auth end to end:

```text theme={null}
Use NinjaChat to check my balance.
```

Then make something:

```text theme={null}
Use NinjaChat to compare three image models for a neon koi poster.
Quote the comparison under $0.25 and wait for approval before generating.
```

<Warning>
  Treat `nj_sk_` keys like passwords — prefer user-level config over committed files, and revoke anything that leaks.
</Warning>

## Troubleshooting

| Problem                                  | Fix                                                                                                                        |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| New tools such as voiceovers are missing | Refresh the connection's tool list, then start a new chat. In ChatGPT Plugins, open the connection and select **Refresh**. |
| `401` or invalid key                     | Copy the complete key with one `Bearer ` prefix, or reconnect OAuth.                                                       |
| Claude Code reports a missing name       | Keep the server name and URL before `--header`, as shown above.                                                            |
| A video is still processing              | Keep its `generation_id` and call `get_generation_status`; do not resubmit.                                                |
| A reference cannot be accessed           | Provide a direct image URL or a file the agent can actually upload. A product webpage is not an image URL.                 |
| Insufficient credit or a spending limit  | Review [Billing & limits](/mcp/billing). Reconnecting does not change your balance.                                        |