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.
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/mcpIt 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/mcpThen run /mcp in Claude Code and choose synento to sign in.
Cursor
Install in one click:
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: untrustedThen run:
hermes mcp login synento
hermes mcp test synentoIn 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-pluginOther 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/listandping, so the client can connect and show the tools straight away. - Anything else without a token, such as
tools/callorresources/read, gets a401whoseWWW-Authenticateheader 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:
| Permission | Lets the agent |
|---|---|
mcp:read | Read projects, sessions, usage and session manifests |
mcp:write | Create sessions and connection tokens, and run media checks |
keys:mint | Create restricted server keys for your app's environment |
projects:create | Create 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
| Tool | What it does |
|---|---|
get_account | The organisation, the signed-in person, the projects this connection may use, plan usage and limits, and the scopes granted. |
list_projects | The projects this connection may use. |
create_project | Create a project; the connection can use it straight away. Accepts an idempotency_key. |
create_session | Create a session. Accepts an idempotency_key, so a retry never makes a second one. |
create_connection_token | A short-lived token (live or replay) for one participant to join from a browser, for trying things locally. |
list_sessions | Recent sessions in a project. |
create_server_key | A restricted rk_live_ key for your app's server-side environment, returned once. |
get_session_manifest | Every participant and track that actually holds recorded media. |
verify_session | Returns whether each expected participant's tracks hold media, and on failure what is missing and the usual cause. |
request_transcript | Transcribe 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_transcript | A session's transcript: status, languages, and cues with speaker, language, text and times. |
run_media_check | Publishes 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_guide | Any of these guides. The same pages are available as MCP resources. |
The loop your agent follows
-
get_account: see which projects it may use. -
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=… -
Write the integration. The server creates sessions and mints connection tokens with
@synento/node; the browser joins with@synento/clientusing only the short-lived connection token. See Getting started. -
Run the app and publish camera and microphone into a session.
-
verify_sessionon 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 beforeconnect()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/sessionsandPOST /v1/projects/{projectId}/sessionsPOST /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
403witherror="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.