MCP
MCP (Model Context Protocol) connects JoAi agents to Cursor, Claude, ChatGPT, and other MCP clients. Tools are gated by installed native apps plus core agent tooling.
New users can start without opening the JoAi UI first: copy the marketing setup prompt from joai.ai, paste it into an MCP client, complete OAuth, and create/name an agent there if needed. See MCP connect and Getting started.
Endpoints
| Endpoint | Use |
|---|---|
https://cortex.joai.ai/mcp | Unified MCP (OAuth; optional ?agent={uuid} prefill) |
https://cortex.joai.ai/mcp/agents/{agentUuid} | Agent-scoped (OAuth; prompt_agent may be x402-gated) |
https://cortex.joai.ai/mcp/apps/{appSlug} | App / brand MCP |
Discover OAuth: GET https://cortex.joai.ai/.well-known/oauth-authorization-server
Server card (name, transport, and a preview tool list — confirm live tools with tools/list): https://joai.ai/.well-known/mcp/server-card.json
Full machine contract: SKILL.md.
Two MCP ideas
- Agent MCP — unified tool catalog for a team agent (this page)
- Dynamic MCP per Warp — Warps/ChatApps can expose MCP servers for publishing into ChatGPT etc. — see ChatApps
Core tools
Always useful (confirm with tools/list):
| Tool | Purpose |
|---|---|
prompt_agent | Chat / instruct the agent (room-aware) |
joai_agent_info / joai_list_agents | Agent metadata |
list_public_teams | Public teams |
ingest_knowledge | Queue ingestion |
Team admin tools
create_team, update_team, update_team_place, update_team_settings
Agent tooling (examples)
| Area | Tools |
|---|---|
| Studio | studio_send, studio_produce, studio_wait, studio_export |
| Memories | create_memory, update_memory, search_memories |
| Skills | list_skills, create_skill, update_skill, delete_skill |
| Documents / media | list_documents, create_document, … · media_list, media_upload, media_delete |
| Private warps / apps | list_private_warps, create_private_warp, … · create_private_app |
| Rooms | list_rooms, get_room_messages |
| Secrets | secret_list, secret_status, secret_set, secret_clear (keys/status only — never values) |
| Misc | execute, search, character_update, create_api_token, check_warp_executions |
Native-app tools (Board, Shop, Contacts, Forms, …) are documented on each native app page.
Rooms
Create/reuse durable MCP rooms:
POST https://api.joai.ai/mcp/rooms
Pass room into prompt_agent. Stream: GET https://cortex.joai.ai/agents/stream/{roomId}?key={secKey}
Manage rooms in product under Agent settings → Rooms.
Credits & usage
MCP tool calls consume credits from your plan. See Billing.
Credit cost per call
| Call Type | Credits |
|---|---|
| Read (query, data fetch) | 1 credit |
| Write (transfer, contract interaction) | 2 credits |
Plan allowances
| Plan | MCP Credits / month |
|---|---|
| Free | 50 |
| Starter | higher |
| Pro / Business | higher |
Exact numbers appear in-app under Usage & Billing. Credits reset each billing cycle.
Related
- MCP integration — connect from Agent settings
- Agents
- Native apps
- Billing
- x402
- Google A2A
- ChatApps
- API
- Integrations
- SKILL.md