Client setup

Every client uses the same URL:

https://www.ninjachat.ai/api/mcp

Claude and ChatGPT use OAuth. For editors and CLIs, create a connection key in 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.

Claude (claude.ai)

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.

ChatGPT

Settings → Security and login → Developer mode, then 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.

Cursor

~/.cursor/mcp.json

{
  "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.

Claude Code

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.

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

Codex

~/.codex/config.toml

[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.

TOML is picky: [mcp_servers.ninjachat] with an underscore, and http_headers as an inline table.

VS Code

.vscode/mcp.json

{
  "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.

Hermes

~/.hermes/config.yaml

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.

OpenClaw

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.

Review or disconnect OAuth agents anytime in 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:

Use NinjaChat to check my balance.

Then make something:

Use NinjaChat to compare three image models for a neon koi poster.
Quote the comparison under $0.25 and wait for approval before generating.

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

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. Reconnecting does not change your balance.

Get Started

Using It

Reference

Building your own OAuth client

Test it

Troubleshooting

​Building your own OAuth client

​Test it

​Troubleshooting

Building your own OAuth client

Test it

Troubleshooting