MCP Setup

Don't want MCP? Download noukai-prompt.md instead — zero-config, works immediately.

Add the MCP Server

Run this in any project directory:

/mcp add --transport http noukai https://api.noukai.xyz/api/v1/mcp/

That's it. Claude Code handles the rest — no API key needed. (note: It needs the trailing slash after mcp)

On your first tool call, Claude Code opens your browser to sign in with your Noukai account. Click Allow on the consent screen and the browser closes automatically.

The token is stored in Claude Code's keychain — you won't see the browser again until the session expires.

Verify

Ask Claude Code:

"List my Noukai flows"

Claude will call hydrate_project and show your project's current state. If it works, you're ready to build.

How It Works

When you add the server, Claude Code:

Probes the MCP endpoint and receives a 401 with a WWW-Authenticate header
Discovers the OAuth authorization server via RFC 9728 metadata
Registers as a client (dynamic client registration)
Opens your browser to app.noukai.xyz/mcp-consent for sign-in
Exchanges the authorization code for a Supabase JWT (with PKCE)
Stores the token and auto-refreshes it when it expires

This follows the standard OAuth 2.1 + PKCE flow — no API keys to manage, rotate, or paste.

Alternative: Manual Configuration

If you prefer to edit .mcp.json directly:

{
  "mcpServers": {
    "noukai": {
      "type": "http",
      "url": "https://api.noukai.xyz/api/v1/mcp"
    }
  }
}

No Authorization header is needed — OAuth handles authentication automatically.

API keys (nk_...) are not accepted by the MCP server. The HTTP endpoint requires an OAuth-issued Supabase JWT, scoped to the signed-in user's project access. There is no way to call MCP tools with a static key.

Troubleshooting

Issue	Cause	Fix
Browser didn't open	OAuth URL not detected	Check Claude Code logs for the URL; paste it manually
"Authorization denied"	Clicked Deny on consent	Remove and re-add the server: `/mcp remove noukai` then re-add
Token expired	Session revoked in Noukai	Claude Code auto-refreshes; if refresh fails, re-authorize via `/mcp remove` + re-add
"Unknown tool: hydrate_project"	MCP server not connected	Check `/mcp list` output, verify the URL
Connection refused	Server unreachable	Check network, verify URL

Other MCP Clients

The configuration above is for Claude Code. For other clients that support OAuth 2.1 + PKCE:

Cursor: Use the same .mcp.json format in your project root
Custom clients: Connect to https://api.noukai.xyz/api/v1/mcp. On 401, follow the WWW-Authenticate header to discover the OAuth server.

The server implements the standard MCP streamable HTTP transport with RFC 9728 protected-resource metadata.

Quick Setup