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).

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.

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/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.

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.

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.

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.

Related pages

• Authentication — the scope list, shared with API keys.

• API reference — the REST endpoints behind each tool.

• Rate limits & errors — error semantics for tool calls.