Unabyss MCP API Reference

The Unabyss MCP server exposes a Model Context Protocol (MCP) API over HTTPS. Clients send JSON-RPC 2.0 requests to a single endpoint and receive JSON responses. The server implements MCP protocol version 2025-06-18 with tools (no static resources).

Base URL

All requests use POST. There is no REST-style path per tool; tools are invoked through the JSON-RPC tools/call method.

Authentication

Send a bearer token on every request:

Authorization: Bearer unby_mcp_...
Content-Type: application/json
Accept: application/json

Static bearer tokens

1. Sign in at app.unabyss.com/mcp.
2. Click Generate token and copy the plaintext value (shown once).
3. Tokens use the unby_mcp_ prefix.

Revoke or edit token permissions from the same page.

OAuth 2.0 (optional)

Unabyss also supports OAuth 2.0 authorization code + PKCE for MCP hosts that implement dynamic client registration. Discovery metadata is published at:

• https://mcp.unabyss.com/.well-known/oauth-protected-resource
• https://mcp.unabyss.com/.well-known/oauth-authorization-server

Supported scopes: read, write.

JSON-RPC envelope

Every request body is a JSON object:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "<method>",
  "params": {}
}

Successful responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}

Error responses use HTTP status codes that match the error class (401, 400, 429, etc.) and a JSON-RPC error object:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Human-readable message",
    "data": {
      "code": "unauthorized"
    }
  }
}

The data.code field carries a machine-readable MCP error code (see Error codes).

Methods

initialize

Handshake. Returns server info and capabilities.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

Result (abbreviated)

{
  "protocolVersion": "2025-06-18",
  "serverInfo": {
    "name": "unabyss-mcp",
    "version": "0.1.0"
  },
  "capabilities": {
    "tools": { "listChanged": false },
    "prompts": { "listChanged": false }
  },
  "instructions": "..."
}

tools/list

Returns all tools the authenticated token may call. Use this to verify credentials without running a heavy tool.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Result (shape)

{
  "tools": [
    {
      "name": "query",
      "description": "...",
      "inputSchema": { "type": "object", "properties": {}, "required": [] }
    }
  ]
}

tools/call

Invoke a tool by name.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "whoami",
    "arguments": {}
  }
}

Result (shape)

{
  "content": [
    {
      "type": "text",
      "text": "Answer or JSON string"
    }
  ],
  "isError": false,
  "structuredContent": {}
}

• content[0].text - primary text payload (always present for successful calls).
• structuredContent - optional typed JSON for tools that return structured data (e.g. store, export_list).

Tools

The table lists tools exposed by the Unabyss MCP server. Call tools/list for the live catalog including input schemas.

Additional tools (propose_connection, update_identity, export_create, export_refresh) are available to full MCP clients but are not required for automation integrations.

Example: whoami

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "whoami",
    "arguments": {}
  }
}

Example: query

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "question": "What projects am I working on?"
    }
  }
}

Example: store

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "store",
    "arguments": {
      "memory": "Prefers OAuth over static API keys for third-party integrations."
    }
  }
}

Structured response acknowledges the store request:

{
  "content": [{ "type": "text", "text": "{\"status\":\"queued\"}" }],
  "isError": false,
  "structuredContent": {
    "status": "queued"
  }
}

Example: list_integrations

No arguments. Returns two arrays: connected (one row per live connection with sync metadata) and available (catalog apps the user has not connected yet).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_integrations",
    "arguments": {}
  }
}

Structured response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"connected\":[...],\"available\":[...]}"
    }
  ],
  "isError": false,
  "structuredContent": {
    "connected": [
      {
        "slug": "github",
        "display_name": "GitHub",
        "icon_url": null,
        "kinds": ["github_repo"],
        "items_count": 12,
        "last_sync_date": "2026-06-01T10:00:00Z",
        "kind": "oauth",
        "uid": "42",
        "id": null,
        "pipedream_account_id": null
      }
    ],
    "available": [
      {
        "slug": "gmail",
        "display_name": "Gmail",
        "icon_url": null,
        "connect_mechanism": "pipedream"
      }
    ]
  }
}

Use available[].slug as the app argument to propose_connection. There is no include_all parameter — both lists are always returned.

Agentic query polling

agentic_query may respond immediately or return a pending job:

{
  "structuredContent": {
    "status": "pending",
    "query_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "poll_after_seconds": 5
  }
}

Poll with agentic_query_read and the same query_id until status is completed or failed.

Error codes

Machine-readable codes appear in error.data.code:

Rate limits and credits

• query, whoami, and read-only tools share query-rate throttles per token.
• store has separate hourly and daily write limits.
• agentic_query has a dedicated deep-query hourly cap.
• Billable operations consume Unabyss credits according to the account plan.

Support

• Product and token management: app.unabyss.com/mcp
• General inquiries: unabyss.com
• MCP protocol specification: modelcontextprotocol.io