> For the complete documentation index, see [llms.txt](https://ovion-studio.gitbook.io/keryo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovion-studio.gitbook.io/keryo-docs/developers/mcp-connector.md).

# MCP connector

The Keryo MCP connector — tools, OAuth 2.1 auth, connecting from an AI client, and self-hosting.

The **Keryo connector** is a remote **MCP server** that exposes Keryo to AI clients such as Claude. It lets an assistant list connected accounts, read posts and statistics, and create, schedule, or publish posts on your behalf — using natural language.

## What is MCP?

The **Model Context Protocol (MCP)** is an open standard that lets AI clients connect to external tools and data through a well-defined server interface. An MCP client (the AI app) discovers the tools a server offers and calls them on the user's behalf. The Keryo MCP server presents Keryo's actions as a small set of tools.

## Tools

The Keryo connector exposes exactly six tools. Each enforces the **same scopes** as the equivalent REST endpoint.

| Tool                        | Scope           | What it does                                           |
| --------------------------- | --------------- | ------------------------------------------------------ |
| **List connected accounts** | `accounts:read` | List a workspace's connected social accounts.          |
| **List posts**              | `posts:read`    | List posts in a workspace.                             |
| **Get statistics**          | `stats:read`    | Read current analytics for a platform in a workspace.  |
| **Create a draft post**     | `posts:write`   | Create a draft (optional media).                       |
| **Schedule a post**         | `posts:publish` | Schedule an existing draft for a future ISO-8601 time. |
| **Publish a post now**      | `posts:publish` | Immediately publish an existing draft (irreversible).  |

{% hint style="info" %}
**Plan gating still applies.** As in the REST API, *Get statistics* requires a **Studio** (or higher) plan on top of `stats:read`. Only **LinkedIn** and **X** are live for statistics today.
{% endhint %}

## Authentication (OAuth 2.1)

The connector authenticates end users with **OAuth 2.1**. The **Keryo backend is the authorization server**; the MCP server verifies the backend-signed JWT access token and forwards it to the REST API.

* The authorization server advertises its metadata at `/.well-known/oauth-authorization-server`.
* When a request arrives without a valid token, the server responds with `401` and a `WWW-Authenticate` challenge that points clients at the protected-resource metadata so they can discover the authorization server:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource"
```

The AI client follows the challenge, runs the OAuth 2.1 flow against the Keryo backend, and obtains a scoped access token. The token carries the scopes the user granted, and every tool call is checked against them.

## Connecting the Keryo connector in an AI client

As an end user, add the Keryo connector to an MCP-capable AI client (such as Claude):

1. In your AI client's connector / MCP server settings, **add a new MCP server** and enter the Keryo MCP server URL — for example `https://mcp.keryo.io`.
2. The client discovers the authorization server and starts the **OAuth 2.1** flow. Sign in to Keryo.
3. **Grant the scopes** the connector requests. Grant only what you need — for read-only use, you can withhold `posts:publish`.
4. Once authorized, the connector's tools become available and the assistant can act on your workspaces within the granted scopes.

{% hint style="warning" %}
**Publish is irreversible.** Granting `posts:publish` lets the assistant publish immediately. If you only want it to draft and schedule for your review, withhold that scope.
{% endhint %}

## Self-hosting the MCP server

If you run the MCP server yourself, configure it with these environment variables:

| Variable           | Default | Purpose                                                                                |
| ------------------ | ------- | -------------------------------------------------------------------------------------- |
| `PORT`             | `3002`  | Port the MCP server listens on.                                                        |
| `BACKEND_URL`      | —       | URL of the Keryo REST backend the server forwards to.                                  |
| `OAUTH_ISSUER_URL` | —       | URL of the OAuth 2.1 authorization server (the Keryo backend).                         |
| `PUBLIC_URL`       | —       | The MCP server's own public URL (e.g. `https://mcp.keryo.io`).                         |
| `JWT_SECRET`       | —       | Shared secret used to verify backend-signed JWT access tokens. Must match the backend. |

{% hint style="danger" %}
`JWT_SECRET` must be the **same** value on the MCP server and the Keryo backend. If they differ, token verification fails and every tool call returns `401`.
{% endhint %}

## Related pages

* [Authentication](/keryo-docs/developers/authentication.md) — the scope list, shared with API keys.
* [API reference](/keryo-docs/developers/api-reference.md) — the REST endpoints behind each tool.
* [Rate limits & errors](/keryo-docs/developers/rate-limits-and-errors.md) — error semantics for tool calls.