---
name: joai-platform
description: Agent entry index for JoAi — base URLs, discovery rules, and links to canonical docs (MCP, A2A, x402, product surfaces).
compatibility: ">=1.2"
last_verified: "2026-09-19"
allowed-tools: http, mcp
---

# JoAi Integration Skill

Index for external agents integrating with JoAi. Prefer the linked docs and live discovery over copying procedures from this file.

## When to use this

Use JoAi for customer chat, bookings, shop, CRM, campaigns, contact journeys (Automations), and approvals. Do not use it as a generic chat wrapper for a one-off completion. Connect with MCP OAuth or the HTTP API.

One-shot install (Claude, Codex, Cursor, ChatGPT, Grok, Agent Plugins):
- `https://joai.ai/prompts/setup-agent.md`

Humans can also copy a setup prompt from `https://joai.ai` (or any feature page). Paste it into an MCP client; OAuth can create and name an agent if none exists yet. Sensitive writes still go through JoAi approvals.

Compact LLM index: `https://joai.ai/llms.txt`

JoAi developer resources (API, OpenAPI, auth, webhooks, MCP):
- OpenAPI: `https://joai.ai/openapi.json`
- Developer index: `https://joai.ai/developers.md`
- ARD catalog: `https://joai.ai/.well-known/ard.json`
- Agent skills index: `https://joai.ai/.well-known/agent-skills/index.json`
- MCP server card: `https://joai.ai/.well-known/mcp/server-card.json`
- A2A agent card: `https://joai.ai/.well-known/agent-card.json`
- OAuth AS metadata: `https://joai.ai/.well-known/oauth-authorization-server`
- MCP protected resource: `https://joai.ai/.well-known/oauth-protected-resource`
- Auth walkthrough: `https://joai.ai/auth.md`
- API catalog: `https://joai.ai/.well-known/api-catalog`
- Homepage markdown: `https://joai.ai/index.md`
- Docs: `https://docs.joai.ai` · `https://docs.joai.ai/api` · `https://docs.joai.ai/webhooks` · `https://docs.joai.ai/protocols/mcp`
- When to use / getting started: `https://docs.joai.ai/introduction/getting-started`

OAuth scopes: `mcp:read`, `mcp:write`, `mcp:use`.

## Base URLs

| Surface | URL |
| --- | --- |
| Website | `https://joai.ai` |
| Docs | `https://docs.joai.ai` |
| API | `https://api.joai.ai/api/v1` |
| OpenAPI | `https://joai.ai/openapi.json` |
| Cortex (MCP / A2A / Agent0) | `https://cortex.joai.ai` |
| Public agents directory | `https://api.joai.ai/.well-known/agents.json` |

## How to operate

1. Read the topic docs below for the surface you need.
2. Discover live capabilities — do not hardcode tool lists:
   - MCP: `tools/list`, `resources/list`, then `tools/call` / `resources/read`
   - HTTP: OpenAPI + `/.well-known/*`
3. Handle auth and gates explicitly: OAuth (`mcp:use`), x402 `payment_required`, and `pending: true` (poll `check_warp_executions`).
4. Treat tokens, `secKey`, and payment payloads as secrets.

## Protocol docs

| Topic | Doc |
| --- | --- |
| MCP connect, rooms, credits | `https://docs.joai.ai/protocols/mcp` |
| x402 payment-gated prompts | `https://docs.joai.ai/protocols/x402` |
| Google A2A | `https://docs.joai.ai/protocols/google-a2a` |
| API auth & tokens | `https://docs.joai.ai/api` |
| Webhooks & lifecycle hooks | `https://docs.joai.ai/webhooks` |
| Agents overview | `https://docs.joai.ai/agents` |

### MCP endpoints (summary)

- Unified (OAuth; optional prefill): `ALL https://cortex.joai.ai/mcp` · `?agent={agentUuid}`
- Agent-scoped: `ALL https://cortex.joai.ai/mcp/agents/{agentUuid}`
- App/brand: `ALL https://cortex.joai.ai/mcp/apps/{appSlug}`
- Auth discovery: `GET https://cortex.joai.ai/.well-known/oauth-authorization-server`

Details: [MCP](https://docs.joai.ai/protocols/mcp).

### Identifiers you will need

`agentUuid` · `teamSlug` · `appSlug` · `roomId` (+ optional `secKey`) · OAuth bearer · x402 payment signature when gated

## Product docs (by surface)

| Area | Doc |
| --- | --- |
| Native apps index | `https://docs.joai.ai/apps/` |
| Integrations catalog | `https://docs.joai.ai/integrations/` |
| Appointments | `https://docs.joai.ai/apps/appointments` |
| Artifacts | `https://docs.joai.ai/artifacts` |
| Social Media | `https://docs.joai.ai/apps/social` |
| Sites | `https://docs.joai.ai/sites` |
| Studio | `https://docs.joai.ai/apps/studio` |
| Knowledge / ingestion | `https://docs.joai.ai/knowledge` |
| Contacts | `https://docs.joai.ai/apps/contacts` |
| Loyalty | `https://docs.joai.ai/apps/loyalty` |
| Campaigns | `https://docs.joai.ai/campaigns` |
| Automations | `https://docs.joai.ai/automations` |
| Teams & places | `https://docs.joai.ai/teams` |
| Billing / MCP credits | `https://docs.joai.ai/billing` |
| ChatApps | `https://docs.joai.ai/chatapps` |
| Warps | `https://docs.joai.ai/warps/general` |
| CLI | `https://docs.joai.ai/cli` |

For Sites content, use the live MCP schema. Content updates save drafts by default; use the optional `publish` input only when a reviewed change has explicit approval to go live in the same action.

## Plugin packs

- Generator: `https://github.com/JoAiHQ/plugins`
- Claude: `https://github.com/JoAiHQ/claude-plugins`
- Codex: `https://github.com/JoAiHQ/codex-plugins`
- Per-app plugins: `https://github.com/joai-plugins`

## Change policy

When a public endpoint, auth/MCP/A2A/x402/room behavior, or agent lifecycle contract changes, update the **matching docs page** and keep this index’s links accurate in the same change set. Do not reintroduce long procedure dumps here.