Synento docs
Guides

Connect your agent (MCP)

Connect Claude Code, Cursor, VS Code, or any MCP client to Synento so it can build and verify your video integration.

View as Markdown

Synento runs a remote MCP server. Connect your coding agent to it and the agent can set up a project, write your integration, then prove the video works by reading back what was actually recorded, without you opening a dashboard.

The server is at:

https://api.synento.com/mcp

It speaks Streamable HTTP and authenticates with OAuth 2.1. Anyone can connect and see its tools without signing in. The first time your agent calls one, your browser opens so you can sign in and choose what the agent may do.

MCP directories, registries and scanners can index the server without credentials, either by connecting to /mcp and listing its tools, or by reading the public server card at /.well-known/mcp/server-card.json. Both describe the same tools. The published MCP Registry entry is com.synento/synento (remote-only, same /mcp URL).

Connect

Claude Code

claude mcp add --transport http synento https://api.synento.com/mcp

Then run /mcp in Claude Code and choose synento to sign in.

Cursor

Install in one click:

Add to Cursor

Or add it by hand to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "synento": { "url": "https://api.synento.com/mcp" }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "synento": { "type": "http", "url": "https://api.synento.com/mcp" }
  }
}

Hermes

Hermes Agent uses the same remote server. The configuration that can sign in is a native entry named synento:

mcp_servers:
  synento:
    url: https://api.synento.com/mcp
    auth: oauth
    trust: untrusted

Then run:

hermes mcp login synento
hermes mcp test synento

In a running session, /reload-mcp loads the tools. hermes mcp login opens a browser. A headless run cannot finish it. Do not treat the entry as signed in until hermes mcp test synento reports the tools.

A portable plugin can store the URL only. Its manifest accepts type, url, and headers, not auth, so enabling one does not sign you in. A native entry with the same name replaces the plugin's server, trust included, which is why trust: untrusted is on the native entry. Tools that are not read-only then ask before they run, and they are refused when nobody can answer.

The portable package is Synento/hermes-plugin. Synento is not in the Hermes plugin catalog or the optional MCP catalog, so hermes plugins install synento will not find a listing. After that repository is public, install the package from git, then add the native entry above and sign in:

hermes plugins install https://github.com/Synento/hermes-plugin

Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth will work. Point it at https://api.synento.com/mcp. It discovers the rest itself:

  • Without a token, the server answers initialize, tools/list, resources/list and ping, so the client can connect and show the tools straight away.
  • Anything else without a token, such as tools/call or resources/read, gets a 401 whose WWW-Authenticate header points to /.well-known/oauth-protected-resource/mcp. That is where the client's sign-in starts.

Clients may register dynamically (RFC 7591) or identify themselves with a client ID metadata document.

For a client that can't sign in through a browser (a CI job, a headless agent), create an agent token in the dashboard under Agents and send it as a header:

claude mcp add --transport http synento https://api.synento.com/mcp \
  --header "Authorization: Bearer sat_…"

When you create the token you choose its projects and permissions (by default mcp:read and mcp:write). It expires after 90 days unless you pick another lifetime, up to a year.

What you approve

When the agent connects, Synento shows you who is asking and lets you choose:

  • Projects: the agent can only see and act in the projects you tick.
  • Permissions: one or more of:
PermissionLets the agent
mcp:readRead projects, sessions, usage and session manifests
mcp:writeCreate sessions and connection tokens, and run media checks
keys:mintCreate restricted server keys for your app's environment
projects:createCreate new projects, which it can then use

Whatever you tick, an agent can never see your owner API keys, change billing, invite people, or delete anything. You can disconnect it at any time from the dashboard under Agents; its access ends on its next request.

Tools

ToolWhat it does
get_accountThe organisation, the signed-in person, the projects this connection may use, plan usage and limits, and the scopes granted.
list_projectsThe projects this connection may use.
create_projectCreate a project; the connection can use it straight away. Accepts an idempotency_key.
create_sessionCreate a session. Accepts an idempotency_key, so a retry never makes a second one.
create_connection_tokenA short-lived token (live or replay) for one participant to join from a browser, for trying things locally.
list_sessionsRecent sessions in a project.
create_server_keyA restricted rk_live_ key for your app's server-side environment, returned once.
get_session_manifestEvery participant and track that actually holds recorded media.
verify_sessionReturns whether each expected participant's tracks hold media, and on failure what is missing and the usual cause.
request_transcriptTranscribe a session that has ended: each participant's speech, per speaker and language. Idempotent, and billed per minute of speech past the plan's allowance.
get_transcriptA session's transcript: status, languages, and cues with speaker, language, text and times.
run_media_checkPublishes a synthetic two-person call through Synento and verifies it from the recording. It creates a real session named synento-media-check in the project, which fires your webhooks and counts as a few seconds of usage like any other call.
get_guideAny of these guides. The same pages are available as MCP resources.

The loop your agent follows

  1. get_account: see which projects it may use.

  2. create_server_key: mint a restricted key and write it to your app's server-side environment (.env, which must be gitignored):

    SYNENTO_API_KEY=rk_live_…
    SYNENTO_API_URL=https://api.synento.com
    SYNENTO_PROJECT_ID=…
  3. Write the integration. The server creates sessions and mints connection tokens with @synento/node; the browser joins with @synento/client using only the short-lived connection token. See Getting started.

  4. Run the app and publish camera and microphone into a session.

  5. verify_session on that session. It passes only when each participant's tracks actually hold recorded media. If it fails, it tells the agent what is missing and the usual cause: no audio track in the stream, publishing before connect() resolved, a token for the wrong session.

An agent should not report the integration as working until verify_session passes. If it keeps failing, run_media_check tells a Synento problem from an integration problem: it sends a synthetic call through the same WebSocket endpoint and recording path your app uses. It does not run your code, so it cannot prove your integration works. Only verify_session on your app's own session can.

Restricted server keys

The key an agent writes into your environment is a restricted key (rk_live_…), not an owner API key. It belongs to one project and works on exactly four routes:

  • POST /v1/sessions and POST /v1/projects/{projectId}/sessions
  • POST /v1/sessions/{sessionId}/connection (live and replay tokens)
  • GET /v1/sessions/{sessionId}/manifest

Every other route refuses it. @synento/node works with it unchanged. Keys an agent created are marked as such under Agents in the dashboard, where you can revoke them.

Security

  • Only discovery is public. Without signing in, a client can learn the server's name, instructions, tool names, descriptions and input schemas, and the guide titles. That is the same information as the public server card. It cannot call a tool, read a guide, or see anything about your account.
  • A token that is sent but no longer valid is refused even for discovery, so the client knows to refresh it or ask you to sign in again.
  • Tokens are bound to this server. Access tokens are opaque, last an hour, and are issued for exactly one audience, https://api.synento.com/mcp.
  • PKCE is required for every authorization, and only the authorization-code flow is supported.
  • Refresh tokens rotate on every use. Presenting one that was already used revokes the whole connection.
  • A connection lasts 30 days. Refreshing does not extend it; after that the agent asks you to sign in and approve again.
  • Nothing a token grants outlives its grant. Each request re-checks that the connection is still approved, the person is still in the organisation, and each project still belongs to it.
  • Every tool call is recorded. The dashboard's Agents page shows recent activity: which tool, which project, and whether it worked.
  • Scope is enforced on every call. Calling a tool without the permission it needs returns 403 with error="insufficient_scope", so the client can ask you for more.

A worked example

AI interview recorder is a small Next.js app in the repository: the interviewer creates a link, the candidate joins a recorded 1:1 call, and the app shows the replay and an MP4 export afterwards. The same connection steps, written out for a person, are on For agents.

Troubleshooting

The browser says the request has expired

The sign-in link is valid for 30 minutes. Go back to your agent and connect again.

A tool fails with "requires the … scope"

The connection wasn't granted that permission. Reconnect (in Claude Code: /mcp, then re-authenticate synento) and tick it.

"Project … is not available to this connection"

The agent is using a project you didn't approve. Reconnect and tick it, or allow projects:create and let the agent make one.

On this page