> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.jelliu.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.jelliu.co/_mcp/server.

# MCP server

Jelliu hosts a remote [Model Context Protocol](https://modelcontextprotocol.io) server. It exposes your workspace as tools, so an AI assistant can list and create agents, run campaigns, manage contacts, send messages, place calls and read analytics from a conversation.

Every tool is a thin wrapper over the REST API. Tool calls go through the same authentication, scopes, validation, rate limits and audit log as any other API request.

## Endpoint

|                |                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------- |
| URL            | `https://mcp.jelliu.co` (also reachable at `https://api.jelliu.co/mcp`)                                 |
| Transport      | Streamable HTTP, stateless, JSON responses. Send JSON-RPC with `POST`; `GET` and `DELETE` return `405`. |
| Authentication | `Authorization: Bearer jl_...` API key, or OAuth 2.1                                                    |
| Health check   | `GET https://mcp.jelliu.co/health` (no authentication)                                                  |

The health check reports the server name, version, transport, supported authentication and the number of tools:

```bash
curl -sS https://mcp.jelliu.co/health
```

## Connect a client

Pick the key's scope on purpose. A `read` key is enough for reporting assistants. Managing campaigns and webhooks needs `full`. See [Scopes and tools](#scopes-and-tools).

### Claude Code

Add the server from the command line:

```bash
claude mcp add --transport http jelliu https://mcp.jelliu.co \
  --header "Authorization: Bearer jl_your_api_key"
```

Or commit a project-level `.mcp.json`, reading the key from the environment instead of hard-coding it:

**`.mcp.json`**

```json title=".mcp.json"
{
  "mcpServers": {
    "jelliu": {
      "type": "http",
      "url": "https://mcp.jelliu.co",
      "headers": {
        "Authorization": "Bearer ${JELLIU_API_KEY}"
      }
    }
  }
}
```

### Cursor

Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

**`mcp.json`**

```json title="mcp.json"
{
  "mcpServers": {
    "jelliu": {
      "url": "https://mcp.jelliu.co",
      "headers": {
        "Authorization": "Bearer jl_your_api_key"
      }
    }
  }
}
```

### Claude.ai and other connector-based clients

Add a **custom connector** with the URL `https://mcp.jelliu.co`. No key is needed: the client discovers Jelliu's OAuth server, opens a Jelliu sign-in and consent screen, and receives its own short-lived credentials. See [OAuth](#oauth).

## Authentication

### API key

Send a workspace API key exactly as for the REST API. Create one under **Settings → API Keys** in the dashboard; see [Authentication](/authentication).

A missing, malformed, revoked or expired key returns HTTP `401` with a JSON-RPC error and a `WWW-Authenticate` challenge that points OAuth-capable clients to the discovery document:

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized — supply a valid Jelliu API key (jl_…) in the Authorization: Bearer header."
  },
  "id": null
}
```

### OAuth

The MCP server is also an OAuth 2.1 authorization server for public clients.

|                               |                                                                |
| ----------------------------- | -------------------------------------------------------------- |
| Protected resource metadata   | `https://mcp.jelliu.co/.well-known/oauth-protected-resource`   |
| Authorization server metadata | `https://mcp.jelliu.co/.well-known/oauth-authorization-server` |
| Dynamic client registration   | `POST https://mcp.jelliu.co/oauth/register`                    |
| Authorization                 | `GET https://mcp.jelliu.co/oauth/authorize`                    |
| Token                         | `POST https://mcp.jelliu.co/oauth/token`                       |
| Revocation                    | `POST https://mcp.jelliu.co/oauth/revoke`                      |
| Grants                        | `authorization_code`, `refresh_token`                          |
| PKCE                          | Required, `S256`                                               |
| Scope                         | `mcp`                                                          |

How the grant works:

* The person approving the connection signs in to Jelliu and approves it on a consent screen. Any member of the workspace can approve.
* The access token is a Jelliu API key that expires after **1 hour**. Refresh tokens last **90 days** and are single-use: each refresh returns a new one.
* The token never has more access than the person who approved it. Approval by a workspace **owner or admin** yields `full` scope; approval by anyone else yields `read` and `write`.
* Refreshing stops working if the approving person is no longer a member of the workspace.

## Scopes and tools

The key's scope decides which tools the client can see at all:

| Scope   | Read tools | Write and operational tools | Admin-only operations         |
| ------- | ---------- | --------------------------- | ----------------------------- |
| `read`  | Listed     | Hidden                      | Not available                 |
| `write` | Listed     | Listed                      | Refused with `403` by the API |
| `full`  | Listed     | Listed                      | Allowed                       |

"Admin-only operations" are the REST routes restricted to administrators, such as creating, activating or deleting campaigns. A `write` key sees those tools, but the call fails. For an assistant that manages the whole workspace, use a `full` key.

Tools that depend on a connected app, such as accounting integrations, are listed only when that integration is connected to the workspace.

Some operations are **never** exposed over MCP and stay in the dashboard:

* creating or revoking API keys;
* billing purchases (checkout, minute packs, phone numbers);
* contact data erasure.

Tools that place calls or send messages act immediately and incur cost. Configure your assistant to confirm before it uses them.

## Limits and errors

* **Rate limits.** The MCP endpoint accepts 120 requests per minute per client IP. Each tool call is also an API request and counts against your workspace's [rate limits](/rate-limits).
* **Plan.** Access to the MCP server is part of your workspace plan and is included in every current plan. If a plan does not include it, the server answers `403` with JSON-RPC error code `-32003`.
* **Suspended workspace.** Requests return `403` with JSON-RPC error code `-32002`.
* **Temporary unavailability.** `503` with `Retry-After: 5` and JSON-RPC error code `-32002`.

Error messages from the MCP server may be in Spanish, like other product-facing messages. Rely on the HTTP status and the JSON-RPC `code`.