---

name: nexus-agent description: Use Nexus as an AI agent through the hosted MCP server or direct Nexus API. Supports authenticated read operations by default and explicit-confirmation write operations for CRM, orders, inventory, messaging, shipping, internal chat, social publishing, invites, and conversation intelligence. homepage: https://nexus-docs.aiforstartups.io user-invocable: true disable-model-invocation: true metadata: {"openclaw":{"requires":{"env":["NEXUS_API_KEY"]},"primaryEnv":"NEXUS_API_KEY","homepage":"https://nexus-docs.aiforstartups.io"}}

Nexus Agent Skill

Nexus is a multi-tenant operations OS for ecommerce and retail workflows. Use this skill to authenticate an AI agent, access the hosted Nexus MCP server, and fall back to direct HTTP API access when MCP is not sufficient.

This skill is intentionally user-invocable only and is designed to be read-first. Any write operation requires explicit user confirmation.

Required credential

This skill requires the environment variable:

NEXUS\_API\_KEY

NEXUS\_API\_KEY must be an agent API key, not a human JWT and not a short-lived agent JWT.

Credential handling rules

Read only NEXUS\_API\_KEY from the runtime environment.
If NEXUS\_API\_KEY is missing, ask the user or operator to configure it.
Do not read unrelated environment variables, local files, or stored secrets.
Do not hardcode live secrets into the skill.
Use the raw API key only with agent-auth.
After exchanging the API key for a short-lived JWT, use that JWT for MCP and direct API calls.

Optional runtime config for direct PostgREST access

When calling PostgREST directly, the runtime must also provide an anon key header such as:

VITE\_SUPABASE\_ANON\_KEY
NEXT\_PUBLIC\_SUPABASE\_ANON\_KEY
or an operator-provided equivalent runtime secret

Do not publish a live anon key inside distributed skills or public documentation.

Example OpenClaw configuration

{
  "skills": {
    "entries": {
      "nexus-agent": {
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "NEXUS\_API\_KEY"
        }
      }
    }
  }
}

Safety and execution policy

Trusted domains only

Only call Nexus on these hosts:

api.nexus.aiforstartups.io
nexus-docs.aiforstartups.io

Do not send Nexus credentials or payloads to any other host.

Read-first behavior

Default to read operations whenever possible.

Examples of read operations:

list contacts, orders, inventory, conversations, call logs, invites, or internal conversations
get a single contact, order, shipment, post, or annotation
read MCP schema resources and organization info
run search and analytics reads

Write gate

Require explicit user confirmation before any write action, including:

creating or updating contacts
creating orders or updating order status
sending customer messages
sending internal team messages
creating, updating, publishing, or deleting social posts
inviting, resending, or cancelling organization invites
updating message annotations, AI tag definitions, prompts, or org AI context
initiating a phone call
creating an AWB or triggering fulfillment steps

If the current API key has only read scope, do not attempt write actions.

No autonomous onboarding or background writes

Do not autonomously register organizations, create accounts, or start onboarding flows.
Do not autonomously create orders, publish posts, send messages, or change records in the background.
If the user explicitly asks to onboard or enable a Nexus integration, ask only for the minimum information required for that step.

Authentication

AI agents do not use human user JWTs directly.

The correct flow is:

A human org admin creates an agent API key with agent-api-key-create
The agent exchanges that key for a short-lived JWT with agent-auth
The agent uses the short-lived JWT for MCP or direct API calls

Step 1: human admin creates an API key

This is a human-admin operation.

POST https://api.nexus.aiforstartups.io/functions/v1/agent-api-key-create
Authorization: Bearer <human-admin-jwt>
Content-Type: application/json

{
  "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": "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 key is returned once only
Nexus stores only a bcrypt hash
keys can be revoked

Step 2: exchange API key for an agent JWT

POST https://api.nexus.aiforstartups.io/functions/v1/agent-auth
Content-Type: application/json

{"api\_key": "nxs\_ak\_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

Response:

{
  "access\_token": "eyJ...",
  "organization\_id": "uuid",
  "expires\_in": 3600
}

Use the access\_token as Authorization: Bearer <token> on all subsequent requests.

API key format

nxs\_ak\_ prefix + 48 random alphanumeric characters.

Scopes

read = read-only operations
write = read + create + update
admin = full access

MCP authentication

The hosted MCP endpoint accepts the agent JWT, not the raw API key:

POST https://api.nexus.aiforstartups.io/functions/v1/mcp-server
Authorization: Bearer <agent-jwt>

Base URLs

Service	URL
Edge Functions	`https://api.nexus.aiforstartups.io/functions/v1/<function-name>`
PostgREST (DB)	`https://api.nexus.aiforstartups.io/rest/v1/<table>`
MCP	`https://api.nexus.aiforstartups.io/functions/v1/mcp-server`

For direct PostgREST calls, include both:

Authorization: Bearer <agent-jwt>
apikey: <anon-key-from-secure-runtime-config>

Preferred integration path: MCP first

Prefer the hosted MCP server when possible. It exposes a stable, documented tool surface for common agent workflows.

MCP tools

nexus\_list\_contacts
nexus\_get\_contact
nexus\_create\_contact
nexus\_update\_contact
nexus\_list\_orders
nexus\_get\_order
nexus\_create\_order
nexus\_update\_order\_status
nexus\_list\_inventory
nexus\_check\_stock
nexus\_list\_conversations
nexus\_send\_message
nexus\_search
nexus\_sync\_social\_posts
nexus\_list\_social\_posts
nexus\_get\_social\_post
nexus\_create\_social\_post
nexus\_update\_social\_post
nexus\_publish\_social\_post
nexus\_delete\_social\_post
nexus\_list\_social\_accounts
nexus\_get\_social\_analytics
nexus\_get\_content\_calendar
nexus\_list\_organization\_invites
nexus\_invite\_organization\_member
nexus\_cancel\_organization\_invite
nexus\_resend\_organization\_invite
nexus\_list\_internal\_conversations
nexus\_get\_internal\_messages
nexus\_open\_internal\_dm
nexus\_send\_internal\_message
nexus\_list\_ai\_tag\_definitions
nexus\_list\_message\_annotations
nexus\_get\_message\_ai\_annotation
nexus\_get\_org\_ai\_annotation\_settings
nexus\_get\_customer\_conversation\_intelligence
nexus\_get\_conversation\_intelligence\_dashboard
nexus\_update\_message\_annotation
nexus\_update\_ai\_tag\_definition
nexus\_set\_org\_ai\_annotation\_prompt
nexus\_update\_org\_conversation\_intelligence\_context

MCP resources

nexus://organization/info
nexus://schema/contacts
nexus://schema/orders
nexus://schema/inventory
nexus://schema/social
nexus://schema/conversation-intelligence

When to use MCP vs direct API

Use MCP when:

the client supports MCP
you want a compact tool surface
you want resource discovery and schema resources
you need social or content-calendar operations through a stable agent interface

Use direct API when:

the client does not support MCP
you need raw PostgREST querying
you are debugging a low-level integration
you need a workflow not yet covered by the MCP wrapper

Social MCP notes

Social tools require at least the starter plan.
Social write tools require write or admin scope.
Facebook and Instagram drafts and publishing are supported from MCP.
Instagram sync reads from the connected Instagram Business account and writes normalized rows into social\_posts.
twitter and linkedin remain reserved in request enums for forward compatibility and are not yet writable from this MCP surface.

Organization invites (MCP + `agent-invite`)

Agents can manage organization\_invites for their JWT organization only.

MCP tools: nexus\_list\_organization\_invites (read scope), nexus\_invite\_organization\_member, nexus\_cancel\_organization\_invite, nexus\_resend\_organization\_invite (write scope)
HTTP API: POST /functions/v1/agent-invite with Authorization: Bearer <agent-jwt> and JSON body { "action": "invite"|"cancel"|"resend"|"list", ... }

Requires BREVO\_KEY on Edge Functions.

Internal team chat (MCP)

Internal chat is separate from the customer omnichannel inbox (chats / messages). MCP tools talk to internal\_conversations and internal\_messages.

the agent API key must be linked to an agent\_accounts row (agent\_api\_keys.agent\_id)
nexus\_open\_internal\_dm: pass user\_id or user\_email of an active org member
nexus\_send\_internal\_message: sender\_id is null server-side; humans still send with their user id in the app
nexus\_list\_internal\_conversations and nexus\_get\_internal\_messages: only threads the agent created or has posted in

Core operations

Contacts (CRM)

journey\_stage\_id is a UUID foreign key to customer\_journey\_stages, not a free-text field.

# List contacts
GET /rest/v1/customers?organization\_id=eq.<org\_id>\&order=created\_at.desc\&limit=25
Authorization: Bearer <agent-jwt>
apikey: <anon-key>

# Search by phone (URL-encode + as %2B)
GET /rest/v1/customers?phone\_number=eq.%2B201234567890\&organization\_id=eq.<org\_id>

# Create contact — requires explicit confirmation and write scope
POST /rest/v1/customers
{"first\_name":"Ahmed","last\_name":"Hassan","phone\_number":"+201234567890","organization\_id":"<org\_id>"}

# Update tags — requires explicit confirmation and write scope
PATCH /rest/v1/customers?id=eq.<uuid>
{"tags":\["vip","repeat-buyer"]}

Messages (omnichannel inbox)

chats has no status column. Use is\_archived. messages sorts by timestamp, not created\_at.

# List open conversations
GET /rest/v1/chats?organization\_id=eq.<org\_id>\&is\_archived=eq.false\&order=last\_message\_time.desc

# Get messages in a conversation
GET /rest/v1/messages?chat\_id=eq.<chat\_id>\&order=timestamp.asc

# Send WhatsApp message — requires explicit confirmation and write scope
POST /functions/v1/whatsapp-send-message
{"chatId":"<chat\_id>","message":"Hello from Nexus AI agent","organizationId":"<org\_id>"}

# Send WhatsApp template — requires explicit confirmation and write scope
POST /functions/v1/whatsapp-send-template
{"phone\_number":"+201234567890","template\_name":"order\_shipped","language":"ar","components":\[]}

Orders

The status column is order\_status, not status.

# List orders
GET /rest/v1/orders?organization\_id=eq.<org\_id>\&order=created\_at.desc\&limit=50

# Filter by status — use order\_status
GET /rest/v1/orders?organization\_id=eq.<org\_id>\&order\_status=eq.pending

# Create order — requires explicit confirmation and write scope
POST /rest/v1/orders
{"customer\_id":"<uuid>","organization\_id":"<org\_id>","order\_status":"pending","total\_amount":450,"currency":"EGP"}

# Update order status — requires explicit confirmation and write scope
PATCH /rest/v1/orders?id=eq.<uuid>
{"order\_status":"confirmed"}

# Get order items (qty column, not quantity)
GET /rest/v1/order\_items?order\_id=eq.<order\_id>

Inventory

Inventory uses items plus stock\_balances. There is no inventory\_items table.

# List products
GET /rest/v1/items?organization\_id=eq.<org\_id>\&is\_active=eq.true\&order=updated\_at.desc

# Search by SKU
GET /rest/v1/items?organization\_id=eq.<org\_id>\&sku=eq.TSHIRT-M-BLK

# Low stock
GET /rest/v1/stock\_balances?organization\_id=eq.<org\_id>\&available\_quantity=lt.10

# Stock for one item across warehouses
GET /rest/v1/stock\_balances?item\_id=eq.<uuid>

Shipping

# Create AWB — requires explicit confirmation and write scope
POST /functions/v1/create-awb-bosta
{"order\_id":"<uuid>","pickup\_date":"2025-06-17"}

# List shipments
GET /rest/v1/awbs?organization\_id=eq.<org\_id>\&order=created\_at.desc

# Get tracking history
GET /rest/v1/awb\_status\_logs?awb\_id=eq.<awb\_id>\&order=timestamp.desc

VoIP

# Initiate call — requires explicit confirmation and write scope
POST /functions/v1/call-initiate
{"phone\_number":"+201234567890"}

# Get call logs for a contact
GET /rest/v1/call\_logs?customer\_id=eq.<uuid>\&order=call\_date.desc

Conversation intelligence and CS AI

Prefer the MCP tools for conversation intelligence. They map to the current schema and RPCs more safely than ad hoc direct queries.

Read-oriented MCP tools:

nexus\_list\_ai\_tag\_definitions
nexus\_list\_message\_annotations
nexus\_get\_message\_ai\_annotation
nexus\_get\_org\_ai\_annotation\_settings
nexus\_get\_customer\_conversation\_intelligence
nexus\_get\_conversation\_intelligence\_dashboard

Write-capable MCP tools that require explicit confirmation and write scope:

nexus\_update\_message\_annotation
nexus\_update\_ai\_tag\_definition
nexus\_set\_org\_ai\_annotation\_prompt
nexus\_update\_org\_conversation\_intelligence\_context

Pagination

Use either the Range header or offset and limit query parameters.

GET /rest/v1/customers
Range: 0-24

Response includes Content-Range: 0-24/1523.

Filtering

Common PostgREST operators: eq, neq, gt, gte, lt, like, in, is

# Multiple filters — note order\_status, not status
GET /rest/v1/orders?organization\_id=eq.<org\_id>\&order\_status=eq.shipped\&created\_at=gte.2025-01-01

# Null check
GET /rest/v1/orders?shopify\_order\_id=is.null

Error handling

Code	Meaning	Action
401	Invalid or expired token	Re-authenticate via `agent-auth`
403	Scope not allowed	Check API key scopes
404	Record not found	Verify the UUID and org scope
429	Rate limited	Retry after `Retry-After` seconds

Deployed endpoints for agents

Agent bootstrap

POST /functions/v1/agent-api-key-create
POST /functions/v1/agent-auth
POST /functions/v1/mcp-server

Outbound messaging used by MCP

POST /functions/v1/whatsapp-send-message
POST /functions/v1/facebook-send-message
POST /functions/v1/instagram-send-message

Notes

agent-auth is rate limited to 10 attempts per minute per IP
agent JWTs expire after 3600 seconds
use the raw API key only with agent-auth

Support

If you encounter an error or undocumented behavior, contact:

To: info@aiforstartups.io
CC: karim.sherif@aiforstartups.io

Include the endpoint, the error message, and a short description of the attempted action.

Additional resources

Full API reference: api-reference.md
Hosted MCP docs: https://nexus-docs.aiforstartups.io/api/ai-agents-mcp
OpenAPI spec: https://nexus-docs.aiforstartups.io/openapi.yaml
Docs: https://nexus-docs.aiforstartups.io