Connect Claude to AICtrlNet (MCP)

AICtrlNet exposes its capabilities as MCP tools via Streamable HTTP transport. Claude Code, claude.ai, Claude Desktop, Cursor, or any MCP client can connect and use natural language to create workflows, execute them, assess quality, automate companies, and more.

Tool surface: 194 tools across three editions (51 Community / 158 Business / 194 Enterprise, accretive). Every tool carries a title and MCP annotation hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients can tell a read from a write before calling.

Three ways to connect

Pick OAuth auto-login unless you need to script it — no tokens to paste, sessions survive restarts, Claude Code handles renewal transparently.

Option A: OAuth 2.1 auto-login (recommended)

Zero tokens to copy. Claude Code discovers the authorization server from the MCP endpoint, registers itself dynamically, opens a browser for your approval, and caches the session locally.

Setup

// ~/.claude/mcp.json
{
  "mcpServers": {
    "aictrlnet": {
      "type": "http",
      "url": "https://api.enterprise.aictrlnet.com/api/v1/mcp-transport"
    }
  }
}

That’s it. No headers: block, no key.

First use

1. Restart Claude Code.
2. In any Claude Code prompt, ask to do something that needs AICtrlNet ("list my workflows").
3. Claude Code detects a 401 response pointing at our OAuth metadata, opens your browser.
4. You log into AICtrlNet at aictrlnet.com (if not already).
5. HitLai shows a consent screen: “Claude Code wants to access: read:workflows, write:workflows“. Click Approve.
6. Browser redirects back to Claude Code. Claude Code caches the session.
7. Your prompt runs.

From this point on, you never see a dialog again — refresh tokens roll automatically. To revoke, visit Settings → Authorized Apps on HitLai and click the delete button next to Claude Code.

Scope selection

Claude Code requests scopes based on what you’re about to do. If you later ask Claude to do something that needs a scope you didn’t originally approve, it’ll prompt you again — just for the new scope, not the ones you already granted.

From claude.ai, Claude Desktop or the mobile app (custom connector)

The same OAuth flow works without any config file:

1. In claude.ai open Customize → Connectors → Add custom connector.
2. Name it AICtrlNet and paste the server URL: https://api.enterprise.aictrlnet.com/api/v1/mcp-transport.
3. Click Add, then Connect. Claude registers itself with our authorization server, opens the HitLai consent screen, and returns once you approve.
4. In any chat, enable the connector and ask, for example, “list my workflows”.

Revocation is the same as for Claude Code: Settings → Authorized Apps on HitLai.

Option B: API key (power users / CI)

Best for: scripts, CI/CD workflows, long-running agents, shared / headless machines where you can’t pop a browser.

1. Create the key

1. Log into AICtrlNet → Settings → API Keys → Create API Key
2. Pick scopes per the feature → scope cookbook below. Start narrow; you can regenerate with more scopes later.
3. Optional: set an IP allowlist (one CIDR per line — e.g. 10.0.0.0/8).
4. Optional: set an expiry (1-365 days).
5. Optional: under Advanced, set per-tool rate caps for expensive tools.
6. Click Create. The full key is shown once — copy to clipboard or download as a .env file.

2. Add to Claude Code

{
  "mcpServers": {
    "aictrlnet": {
      "type": "http",
      "url": "https://api.enterprise.aictrlnet.com/api/v1/mcp-transport",
      "headers": { "X-API-Key": "aictrl_live_YOUR_KEY" }
    }
  }
}

Scope-set cookbook

Copy-paste sets for common use cases:

The full scope reference (descriptions and groups) ships in the platform repository as docs/architecture/MCP_SCOPE_REFERENCE.md; your API-key screen in HitLai lists the same scopes with descriptions.

Option C: Bearer JWT (quick testing)

{
  "mcpServers": {
    "aictrlnet": {
      "type": "http",
      "url": "https://api.enterprise.aictrlnet.com/api/v1/mcp-transport",
      "headers": { "Authorization": "Bearer YOUR_JWT" }
    }
  }
}

Grab your JWT from browser dev tools after logging into HitLai. JWT expires in 24h; you’ll need to re-paste it. Use API key or OAuth instead for anything but a one-off test.

Local development / self-hosted

{
  "mcpServers": {
    "aictrlnet-local": {
      "type": "http",
      "url": "http://localhost:8000/api/v1/mcp-transport",
      "headers": { "Authorization": "Bearer dev-token-for-testing" }
    }
  }
}

For self-hosted customers, replace aictrlnet.com with your deployment’s hostname in the OAuth / API-key configs above. Same flows apply. Admin needs to set MCP_PUBLIC_URL=https://aictrlnet.customer.com in the business container so the OAuth metadata document contains absolute URLs.

Verifying it works

claude mcp list

Expect 51 tools on Community, 158 on Business, or 194 on Enterprise — filtered by your tenant’s plan tier automatically.

Quick sanity test:

> list my workflows

Found 3 workflows: Data Validation Pipeline (active), Invoice Processing (active), Customer Onboarding KYC (paused)

Plan-tier behavior

Tools are filtered by your tenant’s subscription tier in tools/list. If you call a tool above your tier, you get -32602 Method not found — this prevents tier-taxonomy leaks (Community can’t even probe Enterprise tool names).

Upgrade path: get_subscription + get_upgrade_options (live on every tier).

Troubleshooting

Tool discovery tips

Some flagship tools Claude Code won’t surface in tool-listing unless you ask:

• self_extend — “Research the API and generate an adapter, then auto-activate if risk score is low." One-call hero for v11.4 self-extending agents.
• automate_company — Describe your company; AICtrlNet builds the full org automation — workflows, agents, pods, departments. Optional industry parameter picks from 41 industry packs.
• list_industry_packs + detect_industry — Browse or auto-detect which vertical pack fits before running automate_company.
• browser_execute — When no adapter exists for a web app, Claude can drive it directly. Sandboxed with SSRF defense + per-tenant Playwright contexts.
• nl_to_workflow — Describe a process in English; get a validated, executable workflow back.
• form_pod / dispatch_swarm — Multi-agent collaboration on complex tasks.

Rate limits + metering

• Per-tool rate buckets: Redis INCR/EXPIRE per principal + tool. Principal format: apikey:<tenant_id>:<key_id>. Override via Settings → API Keys → Advanced.
• Metering: metered tools (create_workflow, send_message, generate_adapter, automate_company, browser_execute, etc.) deduct atomically from your tenant’s llm_calls / browser_actions quota — no concurrent-call overruns.
• Idempotency: pass idempotency_key on metered tool calls to make replays safe. Cached responses live 24h, keyed by (tenant, tool, key).

Revocation

API key

Settings → API Keys → Delete or Regenerate. Delete stops the key immediately (in-flight requests complete, new requests 401). Regenerate rotates the hash — old key stops working, new key is displayed once.

OAuth session

Settings → Authorized Apps → Delete the Claude Code / Cursor / whatever entry. Access and refresh tokens are immediately revoked; the MCP client will start a fresh OAuth flow the next time you use it.

JWT

JWTs cannot be revoked mid-flight — they expire naturally at 24h. If you need to stop an abused session, force the user to re-login; their token_version increments and any JWT minted before that is rejected.

Admin environment variables (self-hosted)

Deep-dive documents (architecture spec, threat model, admin runbook, scope reference) ship with the platform repository under docs/architecture/. Questions: support@aictrlnet.com.