MCP API | Genaya API Reference

Genaya Connect

MCP

Genaya Connect - the Model Context Protocol endpoint ChatGPT, Claude, Claude Code and any MCP client use Genaya through, as a signed-in team member. Root of the API host, not /v1.

POSThttps://api.genaya.com/mcp

The MCP endpoint (JSON-RPC 2.0)

Genaya Connect - the Model Context Protocol server ChatGPT, Claude, Claude Code, Gemini, Copilot Studio, Microsoft 365 Copilot, Cursor, VS Code, Windsurf, Zed, Gemini CLI, Slack, Zapier, Make and your own agents talk to. Streamable HTTP: one JSON-RPC 2.0 message per POST (a batch of at most 20 on protocol versions before 2025-06-18), no server-initiated stream (GET and DELETE answer 405). The body is JSON, 256 KB at most. Methods: initialize (echoes a known protocolVersion, capabilities { tools: { listChanged: false } }, serverInfo { name genaya, version 1.2.0 } and the server instructions, and answers an Mcp-Session-Id header - the session is a capability note: whether the host declared elicitation), ping, tools/list (the full catalog, from memory, no sign-in) and tools/call. notifications/* answer 202 with an empty body; a client RESPONSE whose id starts with el_ is the answer to an elicitation the server raised on an SSE stream (see McpElicitationRequest and McpElicitationResponse) and answers 202 too. Credentials on tools/call: a connection token minted by "Sign in with Genaya" (Authorization: Bearer gny_at_..., a person's connection - a public client with PKCE, or an organization-issued client that also presents its secret at the token endpoint), or a Genaya API key (gny_live_ / gny_test_) whose Allow MCP switch is on under Settings > Developer - read and ask only (whoami and ask_genaya), acting as the member who created the key, never metered on the key's /v1 pool (a question spends Genaya AI credits, exactly like the app, and nothing else). A call without a credential answers 401 with a WWW-Authenticate challenge naming the resource metadata and the scopes, which is what makes a host show its sign-in card; a key that is valid but not allowed here (Allow MCP off, a Zapier sign-in key, the Developer API switched off, a live key on the trial) answers a plain tool error naming Settings > Developer. Send Accept: application/json for one JSON body, or Accept: text/event-stream to have a tools/call answered as a request-scoped SSE stream (a heartbeat comment every 10 seconds, notifications/progress frames when params._meta.progressToken is set, an elicitation/create request frame when genaya_act asks the member to confirm a record change in the chat, then the result). Authentication, scope and the rate windows are decided before the stream opens, so their HTTP statuses stay plain. The MCP-Protocol-Version header is honored (2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25; absent means 2025-03-26; anything else is 400). A browser Origin other than the developer docs is refused with 403 before any work. Every tools/call answer carries the X-RateLimit-* headers of the connection, the day, the organization and (on Genaya AI turns) the member's brain window.

Parameters

Headers

MCP-Protocol-Version

string

The MCP protocol version the client speaks. Absent means 2025-03-26 (batches allowed); 2025-06-18 and later refuse batches. An unknown value answers 400.

Accept

string

application/json for a single JSON body; text/event-stream to stream a tools/call with heartbeats, progress and, when the session declared elicitation, the in-chat confirmation request.

Mcp-Session-Id

string

Returned by initialize (a fresh 32-character id per call); send it back on every later call. A session whose initialize declared capabilities.elicitation may be asked to confirm a record change in the chat - genaya_act then raises an elicitation/create request on the SSE stream instead of handing back the confirm_action handle. An absent or unknown id is accepted: the door is stateless otherwise, and a session that declared nothing simply never gets asked in the chat.

Request body

FieldTypeDescription

jsonrpcrequired

enum2.0

id

any

A string or integer the response echoes. Omit it for a notification.

method

initialize, ping, tools/list, tools/call, or a notifications/* method. Absent on a client response to an elicitation.

params

object

For tools/call - { name, arguments, _meta? }: name is one of the seven tools, arguments is the tool's input object, and _meta.progressToken asks for notifications/progress frames on an SSE stream. For initialize - { protocolVersion, capabilities, clientInfo }; declare capabilities.elicitation ({}) to be asked to confirm a record change in the chat.

name

tools/call - the tool name.

arguments

object

tools/call - the tool's arguments, per its inputSchema.

_meta

object

tools/call - progressToken (string or integer) to receive notifications/progress frames on a text/event-stream response.

protocolVersion

string

initialize - the protocol version the client prefers; a known one is echoed, anything else answers 2025-06-18.

capabilities

object

initialize - the client's capabilities. An elicitation object (even empty) declares that the host renders elicitation/create requests; the session is remembered for 24 hours under the Mcp-Session-Id the answer carries.

clientInfo

object

initialize - { name, version } of the host; the name is logged next to the session, never a value from it.

result

object

On a client response to an elicitation (id el_...) - { action, content? }, see McpElicitationResponse.

Response 200

FieldTypeDescription

jsonrpc

string

id

any

The request id, echoed.

result

object

The result of a tools/call. A denial, a rate-limit window, a bad argument, a key without Allow MCP or a timed-out turn is also a tool result, with isError true and a plain sentence as the text - terminal, never a sign-in loop.

content

array of object

One text block - markdown for ask_genaya and genaya_act (the answer plus one line per proposal), a receipt line for confirm / cancel / undo, a short summary for whoami and list_actions.

structuredContent

object

The tool's typed output (McpWhoamiOutput, McpAskGenayaOutput, McpGenayaActOutput, McpConfirmActionOutput, McpCancelActionOutput, McpUndoActionOutput or McpListActionsOutput). Absent when isError is true.

isError

boolean

true when the text is a denial, a rate-limit notice, a bad-argument message or a timeout.

Errors

400A JSON-RPC error the transport could not accept - -32700 for a body that is not JSON, -32600 for a message that is not JSON-RPC 2.0, an unsupported MCP-Protocol-Version, an empty batch, a batch over 20 messages, or a batch on protocol version 2025-06-18 or later.

401No credential; a malformed, expired or revoked connection token; a token in the URL or the body; an unknown, revoked or expired API key. The WWW-Authenticate header is Bearer error="invalid_token", resource_metadata="https://api.genaya.com/.well-known/oauth-protected-resource/mcp", scope="read ai act send offline_access" (the three wave 1 scopes while actions are not enabled), and the same challenge is echoed in the JSON-RPC error's data and _meta under mcp/www_authenticate (code -32001). Sign in again, or create a key with Allow MCP under Settings > Developer.

403The connection lacks the tool's scope - the five action tools need act, which an API key never holds (WWW-Authenticate Bearer error="insufficient_scope" with the scope string to re-consent with; JSON-RPC code -32003), or a browser Origin that is not the developer docs (a plain { error: "forbidden" } body). A permission, plan, organization-switch, Allow MCP or kill-switch denial is NOT a 403 - it is a 200 tool result with isError true and a plain sentence, so a host never loops on sign-in.

405GET, DELETE or any method but POST. Allow is POST.

413The body is larger than 256 KB (JSON-RPC -32600).

503Genaya could not verify the credential or run the tool (JSON-RPC -32000, Retry-After 30), or the connector is temporarily unavailable (Retry-After 600). Never a WWW-Authenticate challenge - an outage must not disconnect every customer. initialize, ping and tools/list keep answering while the door is dark.

curl -X POST https://api.genaya.com/mcp \
  -H "Authorization: Bearer gny_at_xxx" \
  -H "Accept: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ask_genaya",
    "arguments": {
      "message": "How many appointments do I have this week?"
    }
  }
}'

Example response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "You are **Maria Lopez** (Owner) in **Lopez Plumbing**."
      }
    ],
    "isError": false,
    "structuredContent": {
      "member": {
        "name": "Maria Lopez",
        "role": "Owner"
      },
      "organization": {
        "name": "Lopez Plumbing",
        "industry": "field_services",
        "vocabulary": {
          "client": "Client",
          "appointment": "Appointment"
        },
        "timeZone": "America/Los_Angeles",
        "currency": "USD"
      },
      "plan": "pro",
      "scopes": [
        "read",
        "ai",
        "act",
        "send",
        "offline_access"
      ],
      "actionsAvailable": true,
      "confirmation": {
        "records": "in_chat",
        "sends": "genaya_page"
      },
      "refusedClasses": [
        "money",
        "team",
        "numbers",
        "automations"
      ],
      "undoWindowMinutes": 15,
      "host": "claude_code",
      "membershipRule": "linked organizations are not included",
      "appBaseUrl": "https://app.genaya.com"
    }
  }
}