@ai-setu/mcp

Read this first, agent. This = a Model Context Protocol server for AI Setu. It give YOU (Claude Code, Cursor, any MCP-aware agent) the control-plane ops as tools — onboard a user, mint keys, check balance, top up billing — all conversationally, no SDK code. For runtime inference (chat, embeddings) you no use this — call @ai-setu/client directly. This server is the control surface, not the inference path.

TL;DR — no install, MCP client launch it

npx -y @ai-setu/mcp

Then wire it into your MCP client (Claude Code ~/.claude.json or project .claude.json):

{
  "mcpServers": {
    "ai-setu": {
      "command": "npx",
      "args": ["-y", "@ai-setu/mcp"],
      "env": {
        "AI_SETU_PAT": "tt_pat_...",
        "AI_SETU_TENANT_ID": "00000000-0000-0000-0000-000000000001",
      },
    },
  },
}

(Or npm i -g @ai-setu/mcp for the ai-setu-mcp binary.) Mint a PAT at https://app.aisetu.ai/settings/profile. Use admin:write scope to enable mutations.

Rules for agent

1. Hit a tool error? Call setup_status first. It report which env vars are set. Most errors = missing AI_SETU_PAT.
2. OTP cover BOTH new signup AND returning sign-in. No separate signup vs sign-in tool. verify_otp return existingOrgs[] — you branch on it.
3. OTP tools work with NO PAT set. That the cold-start case — onboard a user from nothing. The other tools need AI_SETU_PAT.
4. Secrets show once. create_org / create_api_key / rotate_api_key return a secret one time. Save it where it belong (see flow below), then tell the user it no come back.
5. New org start at $0. Send the user to topUpUrl before first inference.

Tools

Always available (no PAT needed)

| Tool | Purpose | | -------------- | --------------------------------------------------------------------------------------- | | setup_status | Report which env vars are set; run this first if other tools error. | | start_otp | Email a 6-digit code to begin the OTP flow (new OR existing user). | | verify_otp | Verify the code; return a sessionToken (secret) + existingOrgs[] to branch on. | | create_org | New org for the signed-in user. Return { orgId, workspaceId, apiKey, pat, topUpUrl }. | | use_org | Continue with an org the user already belong to. Return its workspace + a fresh pat. | | get_sso_url | SSO fallback — return a Google / Microsoft OAuth URL when the user prefer SSO over OTP. |

Available when AI_SETU_PAT is set

| Tool | Purpose | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | get_credit_balance | Current credit balance + low-balance flag + top-up URL. | | get_usage_projection | Spend projection: avg/day, month-to-date, projected month-end. | | list_workspaces | All workspaces visible to the PAT. | | create_workspace | New workspace (dev / staging / prod separation). | | list_api_keys | Active keys for a workspace. | | create_api_key | Mint a new key. Secret shown ONCE. | | rotate_api_key | Revoke + remint with a fresh secret. | | revoke_api_key | Permanently revoke a key. | | set_provider_credential | Add/update a BYOK Connection — a slug handle (openai/anthropic/gemini/bedrock/bedrock-mantle/vertex, or Azure/OpenAI-compatible via base_url), reached per request as model @<slug>/<model>. Use the *_env fields to keep secrets out of the transcript. | | list_provider_credentials | List BYOK credentials (secrets never returned — only a keyHint). | | test_provider_credential | Synthetic probe of a stored credential against its upstream. | | remove_provider_credential | Revoke a BYOK credential. | | request_topup_link | Stripe PaymentIntent for adding credit; human must finish payment in browser. |

Tenant-scoped tools (get_credit_balance, get_usage_projection, request_topup_link) fall back to AI_SETU_TENANT_ID when called with no explicit tenant_id.

Onboarding flow — you can run the whole thing from chat

OTP-only, no passwords. Same flow for new and returning users:

1. Ask the user for their email.
2. Call start_otp → AI Setu email a 6-digit code.
3. User paste the code back to you.
4. Call verify_otp → { sessionToken, existingOrgs }.
5. Branch on existingOrgs:
   • none      → ask for an org name, call create_org(sessionToken, name).
   • exactly 1 → confirm, call use_org(sessionToken, orgId).
   • several   → let the user pick, then use_org (or create_org for a new one).
6. create_org / use_org return { apiKey?, pat, tenantId, workspaceId, topUpUrl }.
   - Save apiKey (create_org) as AI_SETU_API_KEY in the user's project .env.
   - Save pat as AI_SETU_PAT in the MCP server config, then restart MCP.
7. Tell the user to visit topUpUrl to add credit before first inference (new orgs start at $0).

Env vars

| Variable | Purpose | | ------------------------------------------ | -------------------------------------------------------------------------- | | AI_SETU_PAT (required for the PAT tools) | Personal Access Token. | | AI_SETU_TENANT_ID (recommended) | Tenant id for billing / usage tools. | | AI_SETU_API_BASE_URL (optional) | Full API URL override (self-host); defaults to production api.aisetu.ai. |

Why separate from @ai-setu/admin?

@ai-setu/admin = TypeScript SDK for direct programmatic use (scripts, CI, apps). @ai-setu/mcp = the conversational surface — it wrap the same SDK and describe each op so an LLM pick the right tool and explain it to the user. Two layers share no state. Multi-step work across tool calls → use this MCP server. Deployed app calling AI Setu in code → use the SDK direct.

The four AI Setu packages — which one you grab

| Package | Use it when | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------- | | @ai-setu/client | Runtime agent / app call inference. Drop-in for openai. | | @ai-setu/admin | Scripts / CI / builder agent run control-plane ops in TypeScript. | | @ai-setu/cli | Same control-plane ops from the shell. | | @ai-setu/mcp | Builder agent (Claude Code, Cursor) drive onboarding + ops conversationally. |

Full agent runbook = llms.txt.

License

MIT.