Skip to content
Sign inGet started
Help · The AIAPI and MCP server
For developers

API and MCP server

Claude, ChatGPT, Cursor or an agent you wrote can work in your workspace the way Ayoh Agent does — read and search mail, leave drafts, file conversations, write notes, move cards, book events — as you, and only as far as you let it.

On this page · 5 sections

Your workspace serves two ways in, with the same tools behind both: an MCP server for any MCP client, and a REST API for anything that speaks HTTP. Both run on your own Worker, in your Cloudflare account, so an agent's calls go where the app's go and nowhere else.

MCP
Address: https://YOUR-AYOH/mcp
For: Claude, ChatGPT, Cursor, VS Code and any other MCP client.
REST
Address: https://YOUR-AYOH/v1
For: Scripts, GPT actions, your own agent loop.
OpenAPI
Address: https://YOUR-AYOH/v1/openapi.json
For: Generated clients and tool loaders.

Connect an agent

Claude and ChatGPT

  1. In the client, add a custom connector and paste your MCP address.
  2. It opens Ayoh in your browser. Sign in if you are asked to.
  3. Ayoh shows which app is asking and what it wants. Untick anything you would rather it did not do, and press Allow.
Connector URL
https://YOUR-AYOH/mcp

No key to copy: the client signs in, and appears in Settings → API & MCP as Signed in, where you can change what it may do or revoke it.

Claude Code

Make a key (below), then run this in a terminal:

claude mcp add --transport http ayoh https://YOUR-AYOH/mcp \
  --header "Authorization: Bearer ayoh_…"

Cursor, Windsurf, VS Code and others

Most clients read an MCP settings file of this shape:

mcp.json
{
  "mcpServers": {
    "ayoh": {
      "url": "https://YOUR-AYOH/mcp",
      "headers": { "Authorization": "Bearer ayoh_…" }
    }
  }
}

Anything else

curl
curl https://YOUR-AYOH/v1/tools/search_mail \
  -H "Authorization: Bearer ayoh_…" \
  -H "Content-Type: application/json" \
  -d '{"query": "invoice"}'

Keys and what they allow

In Settings → API & MCP, name a key after what will use it, tick what it may do, and press Create key. The key starts with ayoh_ and is shown once — copy it then. Only the workspace's owner can make keys, and a key acts as the owner.

Read
Search and read mail, notes, boards, the calendar and contacts, and search the web.
Write
Leave drafts, archive, file and mark mail, write notes, edit cards, events and contacts.
Trash & delete
Move mail to Trash or Spam, delete notes, events and contacts, archive cards.
Send email
Send mail from your addresses, marked as written by an AI agent.
Ayoh Agent
Hand tasks to Ayoh Agent and set up scheduled tasks for it.
Connected apps
Run tools in the apps connected under Connectors.
  • A new key starts with Read and Write: useful, and nothing that leaves the workspace or cannot be undone.
  • A key reads what you read — your addresses and the team inboxes, never a colleague's personal mail.
  • Scopes changes what a key may do from its next call. Revoke ends it at once.
  • Activity lists every call a key made in the last month: which tool, whether it worked, how long it took. What it sent and got back is not kept.
  • Mail an agent sends says an AI agent wrote it, in its headers and in a line at the foot. One call can send at most 5 messages and file at most 50 conversations.

What an agent can do

An agent should start with get_workspace: your workspace's name, its time zone and the time there now — every date the tools take and return is on that clock — the addresses mail goes out from, and what its key may do. A key sees only the tools its scopes reach.

Mail
list_mailboxes, search_mail, list_recent, read_thread, draft_in_mailbox, mark_threads, move_threads, send_email
Contacts
find_contacts, save_contact, delete_contact
Calendar
list_events, create_event, update_event, delete_event
Notes
search_notes, read_note, create_note, write_note, delete_note
Boards
list_boards, read_board, read_card, create_card, update_card, update_checklist, comment_card, archive_card, create_column, update_column, organize_board
Web
web_search, read_url
Ayoh Agent
ask_agent, schedule_task
Connected apps
find_app_tools, describe_app_tool, run_app_tool

Each tool says whether it only reads or can destroy something, so a client can ask you before a send or a delete and not before a search.

Handing work to Ayoh Agent

ask_agent gives Ayoh Agent a task in plain words and returns its answer. It works with its own tools and the permissions you gave it in Settings → Agent, and the conversation appears in Chat for you to read. Pass back the chat_id it returns to carry on the same conversation.

Ready-made prompts

Clients that offer MCP prompts (often as slash commands) get five: daily_brief, triage_inbox, draft_reply, meeting_prep and plan_week. Each is a whole job in one message.

The REST API

Every call carries Authorization: Bearer ayoh_…. Every tool is one POST, with its arguments as the JSON body.

GET /v1
Who the key belongs to, its scopes, the workspace, and these addresses.
GET /v1/tools
The key's tools. Add ?format=openai or ?format=anthropic to get them in that model API's tool format, ready to hand to a model.
POST /v1/tools/{name}
Run a tool. Answers {"ok": true, "result": "…"}.
POST /v1/batch
Up to ten calls in one request: {"calls": [{"tool": "…", "arguments": {…}}]}.
GET /v1/openapi.json
The whole API as OpenAPI 3.1. No key needed.
200
The tool ran.
400
The arguments do not fit: the answer names the field.
401
No key, or the key is not valid (revoked, or never issued).
403
The key does not have the scope this tool needs.
404
No tool by that name.
422
The tool ran and said no — a thread that does not exist, a folder the key may not use. The answer says why.

When it does not work

401 · the key is not valid
The key was revoked or mistyped. Make a new one and paste it whole, ayoh_ included.
403 · needs the … scope
Open the key's Scopes in Settings and tick what the tool needs.
The client cannot find any tools
Check the address ends in /mcp, and that the key has at least Read.
The sign-in page says Only the owner can connect apps
Connecting gives the owner's access, so only the owner can approve it.
A signed-in client stops working
It was revoked, or went unused for 90 days. Connect it again.
PreviousCredits and usageNextSettings and account