AI Agents, API Keys, and MCP

Nexus supports AI agents through either:

Self-registration for a new free-tier agent-owned organization.
A human organization admin creating an agent API key for an existing organization.
The agent exchanging that API key for a short-lived agent JWT.

The short-lived agent JWT is then used to access:

the Nexus MCP server
Supabase PostgREST endpoints protected by agent-aware RLS
Nexus edge functions that accept bearer tokens

Deployed endpoints

Purpose	Method	URL
Self-register a new agent-owned org	`POST`	`https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-register`
Create agent API key	`POST`	`https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-api-key-create`
Exchange API key for agent JWT	`POST`	`https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-auth`
Inspect plan and usage	`GET`	`https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-usage`
Nexus MCP server	`POST`	`https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/mcp-server`

Authentication model

Human users

Human users authenticate with Supabase Auth and receive a standard user JWT.

Human JWTs are used for:

frontend access
admin operations
creating agent API keys

Agent API keys

Agent API keys are long-lived credentials for autonomous agents.

Properties:

format: nxs_ak_ + 48 random alphanumeric characters
the raw key is returned once only
Nexus stores only a bcrypt hash
keys are organization-scoped
keys can be revoked by setting is_active = false

Agent JWTs

Agents do not use the raw API key for normal operations. They first exchange it for a short-lived bearer token:

max lifetime: 1 hour
contains organization_id
contains org_role = agent
contains agent_scopes

The agent JWT is the bearer token used with the MCP server and API requests.

Scopes

Nexus agent scopes are intentionally simple:

Scope	Access
`read`	`SELECT`-style read access only
`write`	read + create + update
`admin`	full access including delete/admin operations

admin implies all lower scopes. write implies read.

Pricing

Plan	Price	Summary
`free`	`$0/mo`	read-only MCP, 50 contacts, 25 orders, no outbound messaging, 500 API calls/day, 30-day retention
`starter`	`$99/mo`	read+write MCP, 500 contacts, 200 orders/month, 1,000 outbound messages, 5,000 API calls/day
`growth`	`$199/mo`	full MCP, 5,000 contacts, unlimited orders, 5,000 outbound messages, 25,000 API calls/day, VoIP + automation
`scale`	`$599/mo`	highest limits, full AI suite, custom integrations, SLA, priority onboarding

Additional agents are billed separately on paid plans:

Starter: $10/agent/month
Growth and Scale: $5/agent/month

Step 0: self-register a free agent-owned organization

For brand-new agents without an existing Nexus organization, call agent-register first.

Request:

curl -X POST "https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-register" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Bahig",
    "agent_platform": "cursor",
    "owner_email": "karim@example.com",
    "organization_name": "Bahig - Personal Assistant",
    "plan": "free"
  }'

Response:

{
  "success": true,
  "organization_id": "org-uuid",
  "api_key": "nxs_ak_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ12",
  "api_key_expires_at": "2026-06-23T01:00:00.000Z",
  "mcp_endpoint": "https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/mcp-server",
  "auth_endpoint": "https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-auth",
  "plan": "free",
  "plan_limits": {
    "contacts": 50,
    "orders": 25,
    "inventory_items": 30,
    "outbound_messages": 0,
    "api_calls_per_day": 500,
    "warehouses": 1,
    "ai_annotations": 0,
    "agents": 1,
    "mcp_scopes": ["read"],
    "data_retention_days": 30
  },
  "message": "Store your API key securely. It cannot be retrieved again."
}

Rate limits:

max 3 registrations per owner_email per day
max 10 registrations per IP per hour
paid plans require human-led upgrade; self-registration is free only

Step 1: create an agent API key

Only organization owner and admin users can create agent API keys.

Request:

curl -X POST "https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-api-key-create" \
  -H "Authorization: Bearer <human-user-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bahig - Karim assistant",
    "scopes": ["read", "write"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "api_key": "nxs_ak_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ12",
  "key_prefix": "nxs_ak_ab12CD34",
  "organization_id": "org-uuid",
  "name": "Bahig - Karim assistant",
  "scopes": ["read", "write"],
  "expires_at": "2026-12-31T23:59:59.000Z",
  "message": "Store this API key now. It is only returned once."
}

Important:

The raw API key cannot be retrieved later.
Store it in a secure secret manager.
Never log it in plaintext.

Step 2: exchange API key for agent JWT

Request:

curl -X POST "https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-auth" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "nxs_ak_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ12"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "organization_id": "org-uuid"
}

Security behavior:

invalid/revoked/expired keys are rejected
the endpoint is rate limited to 10 attempts per minute per IP
every auth attempt is logged
last_used_at is updated on success

Step 3: check usage and plan status

Agents and human admins can inspect current usage:

curl "https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-usage" \
  -H "Authorization: Bearer <agent-or-human-jwt>"

The response includes:

current plan slug and name
usage counters and limits
remaining capacity
warnings when a resource is at or above 80%
upgrade guidance

Step 4: call the MCP server

Use the returned agent JWT:

curl -X POST "https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/mcp-server" \
  -H "Authorization: Bearer <agent-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "my-agent",
        "version": "1.0.0"
      }
    }
  }'

The endpoint uses MCP Streamable HTTP, not the legacy SSE transport.

This implementation currently runs in JSON response mode over Streamable HTTP, which works well for hosted remote agents and API-style MCP clients.

MCP tools

The Nexus MCP server exposes these tools:

Tool	Description
`nexus_list_contacts`	List or search contacts with filters
`nexus_get_contact`	Get full contact details
`nexus_create_contact`	Create a contact
`nexus_update_contact`	Update contact fields
`nexus_list_orders`	List orders with filters
`nexus_get_order`	Get an order with line items
`nexus_create_order`	Create an order
`nexus_update_order_status`	Move order through lifecycle
`nexus_list_inventory`	List inventory items
`nexus_check_stock`	Check stock by item or SKU
`nexus_list_conversations`	List conversations
`nexus_send_message`	Send WhatsApp/Facebook/Instagram messages
`nexus_search`	Search contacts, orders, and inventory

MCP resources

The Nexus MCP server also exposes these resources:

Resource	Description
`nexus://organization/info`	Current organization details and auth context
`nexus://schema/contacts`	Contact schema
`nexus://schema/orders`	Order schema
`nexus://schema/inventory`	Inventory schema

Non-MCP access

Agents can also use the agent JWT directly against:

https://lgwvoomgrwpsgpxwyaec.supabase.co/rest/v1/...
https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/...

For PostgREST requests, include both:

Authorization: Bearer <agent-jwt>
apikey: <anon-key>

The database layer enforces organization isolation and agent scope checks through RLS.

Agent-friendly edge functions

These deployed edge functions are especially relevant to AI agents:

Function	Purpose
`agent-register`	Self-register a free agent-owned organization and receive an initial API key
`agent-api-key-create`	Human admin creates agent API keys
`agent-auth`	Exchange API key for short-lived agent JWT
`agent-usage`	Read current plan, usage counters, and upgrade warnings
`mcp-server`	Remote MCP endpoint for Nexus
`whatsapp-send-message`	Send WhatsApp message
`facebook-send-message`	Send Messenger message
`instagram-send-message`	Send Instagram DM

Best practices

Prefer the MCP server for agent integrations because it gives a stable tool surface.
Use the raw API key only with agent-auth.
Rotate or revoke keys immediately if they are exposed.
Request the smallest scope needed for the agent.
Refresh the agent JWT by calling agent-auth again when it expires.
Treat plan limits as hard ceilings. MCP scopes are capped by the organization's current plan even if an older API key requested broader scopes.

Deployed endpoints​

Authentication model​

Human users​

Agent API keys​

Agent JWTs​

Scopes​

Pricing​

Step 0: self-register a free agent-owned organization​

Step 1: create an agent API key​

Step 2: exchange API key for agent JWT​

Step 3: check usage and plan status​

Step 4: call the MCP server​

MCP tools​

MCP resources​

Non-MCP access​

Agent-friendly edge functions​

Best practices​

Deployed endpoints

Authentication model

Human users

Agent API keys

Agent JWTs

Scopes

Pricing

Step 0: self-register a free agent-owned organization

Step 1: create an agent API key

Step 2: exchange API key for agent JWT

Step 3: check usage and plan status

Step 4: call the MCP server

MCP tools

MCP resources

Non-MCP access

Agent-friendly edge functions

Best practices