MCP Server

Overview

The VerifEye MCP Server is a remotely-hosted Model Context Protocol (MCP) server that exposes VerifEye's face capabilities — analysis, recognition and the collections recognition needs — as tools an AI assistant (such as Claude) can call over Streamable HTTP.

The MCP server enables you to:

• Analyze the face(s) in an image for apparent age and gender, plus momentary emotions and attention
• Onboard a face so the same person is identified on a later image, and compare one image against one onboarded face
• Manage the collections onboarded faces live in, and label a face with your own identifier
• Authenticate once via OAuth — your client never sends an API key
• Choose where each image is processed — in the EU or the US — on every call (data residency)

Your MCP client may ask you to confirm rather more than those. Seven of the thirteen tools carry the protocol's destructiveHint, which many clients turn into a confirmation prompt: the four named above, plus verifeye_identify_face, verifeye_compare_face and verifeye_delete_face_key. The two analysis tools carry it because each consumes the image it is given — an uploaded image is deleted once the call is done, so the same uploadId cannot be analyzed a second time — and because the call is metered. verifeye_delete_face_key carries it because a face whose key is gone can be hard to find again. None of those three destroys a face template.

Prerequisites

• A VerifEye Developer Console account — sign in at the VerifEye Developer Console.
• An MCP-capable client that supports remote MCP servers over OAuth — see Connecting a client for the ones with worked configurations.

Server URL

https://verifeye-mcp-server.realeyes.ai/mcp

The server has a single global endpoint. You choose where each image is processed — in the EU or the US — on every call via the region parameter (eu/us) on every tool, for data residency and compliance. Collections are per region: one created in eu is not visible from us, and a collection that seems to have gone missing is very often in the other region. See Available tools.

The server is listed in the official MCP Registry as ai.realeyes/verifeye. Its registry entry (JSON) lists the same server URL. The URL above is the server's only address: if a registry or directory lists a different one, do not connect to it, and contact us.

Authentication

The MCP server uses OAuth 2.1 (authorization code with PKCE). Authentication happens through a branded VerifEye login and consent screen — you never put an API key into your MCP client.

Authorization flow

1. Your MCP client reads the MCP server's protected-resource metadata and discovers the VerifEye authorization server.
2. The client starts an OAuth 2.1 authorization-code flow (with PKCE) and opens the VerifEye login in your browser.
3. You sign in with your VerifEye Developer Console account and approve the Allow / Deny consent screen.
4. The authorization server returns a short-lived, signed access token scoped to the MCP server. Your client refreshes it automatically until the refresh window lapses.
5. The client calls the MCP server with that token. The server resolves your account's API key on the server side and calls VerifEye on your behalf — the key is never exposed to the client.

Connecting a client

Every client needs two things: the server URL

https://verifeye-mcp-server.realeyes.ai/mcp

and a way to identify itself. Claude Code, Claude, Cursor and the Gemini CLI use a pre-registered client ID — the name you will see on the consent screen — and their tab gives the exact value. ChatGPT, VS Code and Codex identify themselves instead by publishing a Client ID Metadata Document and sending its URL, so for those there is nothing to enter. The server offers no dynamic client registration, so a client that expects to register itself on the fly needs one of the IDs below. There is no client secret either way: every client here is a public client and the flow is secured with PKCE.

When you connect, VerifEye opens in your browser: sign in with your Developer Console account and approve the consent screen. An application VerifEye recognises is named there, with the logo it publishes for itself. An application that identified itself with a metadata document from an address VerifEye does not recognise is shown by that address alone — no name, no logo — because anyone who controls the address chooses what it claims. Either screen shows where the authorization will be delivered. Read it, and approve only if you have just started this sign-in yourself — that is the check that holds, because a name and a local address are the two things an application asking on another's behalf can copy.

claude mcp add --scope user --transport http \
  --client-id verifeye-mcp-claude --callback-port 8080 \
  verifeye https://verifeye-mcp-server.realeyes.ai/mcp

{
  "servers": {
    "verifeye": { "type": "http", "url": "https://verifeye-mcp-server.realeyes.ai/mcp" }
  }
}

{
  "mcpServers": {
    "verifeye": {
      "url": "https://verifeye-mcp-server.realeyes.ai/mcp",
      "auth": { "CLIENT_ID": "verifeye-mcp-cursor" }
    }
  }
}

{
  "mcpServers": {
    "verifeye": {
      "httpUrl": "https://verifeye-mcp-server.realeyes.ai/mcp",
      "authProviderType": "dynamic_discovery",
      "oauth": {
        "clientId": "verifeye-mcp-gemini",
        "redirectUri": "http://localhost:7777/oauth/callback",
        "scopes": ["verifeye"]
      }
    }
  }
}

Providing the image

Three tools take an image — verifeye_identify_face, verifeye_onboard_face and verifeye_compare_face — and each takes it as a public URL. The URL is passed through to the VerifEye Face API, which fetches the image itself: the MCP server never downloads it. None of them accepts the image inline as base64. Inline base64 would mean the assistant writing the encoded image out token by token, which for any image large enough to be usable costs far more time and quota than fetching a URL.

This has one practical consequence: an image attached to the conversation cannot be passed to a tool. The assistant can see such an image but cannot hand the bytes to a tool as an argument. Put the image somewhere reachable and give the assistant that link. Prefer an object-storage pre-signed link that expires in minutes; a durably public URL works too, and exposes the face for as long as it is there. Where the client can reach the internet itself, it can upload the image instead — see If you have no URL: upload the image below.

For a usable result the image should also meet the image requirements: an RGB JPEG or PNG, 300x300 to 2000x2000 pixels and 50–2000 KB, with the face centered, upright, at least 150x150 pixels, and covering 20–80% of the frame.

If you have no URL: upload the image

Where the server offers verifeye_get_upload_url, a client can upload the image instead. The tool hands back a short-lived form, the client posts the file to VerifEye storage, and the image tool then takes the returned uploadId in place of imageUrl — see Available tools for the form and the POST. The image is stored in the region you asked for, deleted the moment the first tool call that uses it returns, and removed by a daily lifecycle sweep if no call ever comes, so nothing is left published anywhere.

This needs a client that can make an outbound HTTPS request of its own, and many cannot. An assistant that runs your tools inside a locked-down sandbox — a browser-based assistant, or a desktop app that runs commands in a container with no egress — does not reach storage at all, and fails with a DNS or connection error rather than a VerifEye one. A command-line client on your own machine has no such limit. A public URL works in both, which is why it stays the path to reach for first.

Consent and retention are your responsibility

These tools process facial (biometric) data, and one of them stores it. You are responsible for obtaining valid, informed consent for that processing before a call runs, and for meeting the requirements of the privacy and biometric-data regulations that apply to the people in your images (e.g. GDPR, BIPA, CCPA). In most places a face template is personal data; in many it is special-category data needing explicit consent. See the Realeyes Privacy Policy.

Three things follow, and they are specific to these tools:

• Prefer a short-lived pre-signed link to a durably public URL. Publishing a face at a stable address exposes it to anyone who finds the address, for as long as it is there. A link that expires in minutes does not.
• Remove the image once the call has returned. VerifEye does not keep the image — not even on onboarding, where what is stored is the template derived from it — and neither should the place you put it for the one call that needed it.
• Onboarding outlives the conversation. verifeye_onboard_face creates a face template that persists until something deletes it, and the assistant that created it will not remember it tomorrow. Write down the faceId it returns, or attach an externalKey you can look the face up by, and keep your own record of who consented to what. verifeye_delete_face is how you honour an erasure request.

Available tools

Thirteen tools, in four groups. Every one of them takes region (eu/us, eu by default) and every result echoes it, because a conversation that has called in both regions has no other way to tell one answer from another.

A tool that fails does so with a code you can branch on — see Errors.

verifeye_identify_face

Analyzes the face(s) in an image and returns the attributes you ask for — apparent age, apparent gender, momentary emotions and momentary attention — from a single VerifEye Face API Identify call. Age and gender are on by default. Emotions and attention are off by default and add a surcharge on every face the call answers about — a fraction of what that face already costs, not a second charge: requesting either emotions or attention applies it, and requesting both does not apply it twice. Turn them on only when you need them.

Pass collectionId to also identify the faces against a collection you have onboarded into. Nothing is ever onboarded by this tool, with or without a collection: a face the collection does not hold comes back as NotExisting with no faceId. That is what makes this, rather than verifeye_onboard_face, the way to check whether a face is already known.

Input parameters:

Enable at least one of age, gender, emotions or attention — a call with all four turned off is rejected.

Result:

Only the attributes you request are included; age, gender, emotions and attention are each omitted when their flag is off. The identity fields — faceId, faceStatus and externalKey — appear only when you passed a collectionId.

{
  "region": "eu",
  "collectionId": "customer-faces",
  "faces": [
    {
      "faceConfidence": 0.999,
      "faceId": "8f14e45f-ceea-467a-9d1f-3c2b7a0f51d2",
      "faceStatus": "Existing",
      "externalKey": "customer-4417",
      "age": { "estimatedAge": 27.5, "uncertainty": 0.2, "reliable": true },
      "gender": "Female",
      "emotions": { "present": ["happiness"], "undetermined": ["empathy"] },
      "attention": { "present": ["presence", "eyesOnScreen"], "undetermined": [] }
    }
  ],
  "unprocessedFaceCount": 0
}

A face the Face API cannot answer for with sufficient confidence has no entry in faces at all, and is not counted in unprocessedFaceCount — so faces can hold fewer entries than the image holds faces even when unprocessedFaceCount is 0. See Face detection restrictions.

The result carries no position and no index: the faces array is ordered by how dominant each face is on the image, not by where it is, so with maxFaces above 1 the position in the array does not say which answer belongs to which person. Where you need that, verifeye_compare_face returns boundingBox for every face it compares, and calling Identify directly returns faces[].face.boundingBox.

Absent versus undetermined

These are two different answers and the result keeps them apart.

An absent attribute was not analyzed. Either you did not request it, or the model that owns it had nothing to report for this face. The tool does not distinguish those two, and neither does the VerifEye Face API underneath it: in both cases the attribute is simply not there.

A signal named in a present group's undetermined list is the opposite claim: the analysis ran, and could not decide that one signal. So "emotions": {"present": ["happiness"], "undetermined": ["surprise"]} means surprise was looked for and could not be told, while no emotions key at all means nothing was looked for. Do not treat a missing attribute as a set of undetermined signals.

Reading emotions and attention

verifeye_onboard_face

Onboards the face(s) in an image into a collection, so the same person is identified by verifeye_identify_face or verifeye_compare_face later. The collection must already exist — create it with verifeye_create_collection.

Input parameters:

Result:

{
  "region": "eu",
  "collectionId": "customer-faces",
  "faces": [
    {
      "faceId": "8f14e45f-ceea-467a-9d1f-3c2b7a0f51d2",
      "faceStatus": "New",
      "externalKey": "customer-4417",
      "faceConfidence": 0.998
    }
  ],
  "unprocessedFaceCount": 0,
  "externalKeyAssigned": true
}

The external key is attached by a second call, because the Face API's onboard takes no key: by the time it runs, the face is already in the collection. So a failure there does not fail the onboarding — the face comes back either way, and externalKeyAssigned, externalKeyError and externalKeyErrorCode say that the key did not stick and why. Retry it with verifeye_set_face_key.

A face with neither a remembered faceId nor an external key can afterwards be removed only by emptying the whole collection, which is why both of those fields matter more here than anywhere else on this page.

verifeye_compare_face

A one-to-one check: compares the face(s) in an image against one face already onboarded in a collection, and answers how similar each is. Use it when you know whose face you are checking against — to search a collection for whoever the image shows, use verifeye_identify_face with the collectionId instead. Nothing is onboarded by this call and the submitted image is not added to the collection.

Input parameters:

Result:

{
  "region": "eu",
  "collectionId": "customer-faces",
  "faceId": "8f14e45f-ceea-467a-9d1f-3c2b7a0f51d2",
  "faces": [
    {
      "similarity": 98,
      "isMatch": true,
      "faceConfidence": 0.998,
      "boundingBox": { "x": 412, "y": 96, "width": 208, "height": 262 }
    }
  ],
  "unprocessedFaceCount": 0
}

With maxFaces at 1, whether the person is on the image at all is simply faces[0].isMatch.

verifeye_delete_face

Deletes one onboarded face. This is the tool to use when someone asks for their face data to be erased.

Input parameters:

Result:

verifeye_list_collections

Lists the face collections on the account in one region, or checks whether one particular collection exists if you pass collectionId. It reads nothing about the faces inside, and onboards nothing. Use it before onboarding or deleting anything, so you work against a collection that is really there rather than a name you assumed.

Input parameters:

Result:

{
  "region": "eu",
  "collections": [
    {
      "collectionId": "customer-faces",
      "description": "Returning customers at the front desk",
      "createdAt": "2026-08-14T09:21:04Z",
      "updatedAt": "2026-09-02T11:47:55Z"
    }
  ],
  "totalCount": 1,
  "truncated": false,
  "found": true
}

Collections are per region. One created in eu is not visible from us, and a collection that seems to be missing is very often in the other region.

verifeye_create_collection

Creates an empty collection to onboard faces into. Nothing is destroyed by this call, and an empty collection costs nothing to keep.

Input parameters:

Result:

The id is permanent: there is no way to rename a collection afterwards, only to change its description. If a collection with that id already exists the call fails with collection_exists and creates nothing — and that existing collection may hold faces that are not yours to add to, so check with verifeye_list_collections first. The collection is created in one region only; create it again in the other region if you need it there.

verifeye_set_collection_description

Replaces a collection's description — the free text that says what it is for. The collection's id and the faces in it are not touched.

Input parameters:

Result:

It replaces rather than appends, so pass the full text you want, and read the current one with verifeye_list_collections first if you mean to extend it.

verifeye_reset_collection

Deletes every face in a collection. The collection itself stays, empty. To remove one person, use verifeye_delete_face; to remove the collection as well, use verifeye_delete_collection.

Input parameters:

Result:

verifeye_delete_collection

Deletes a collection and every face in it.

Before deleting, the tool reads the account's verification configurations in that region. If any of them routes face data into this collection, the call fails with collection_in_use and names them. That refusal cannot be overridden from here — a verification still pointing at the collection means deleting it would break live verifications for real users, so the verification has to be changed in the VerifEye Developer Console first. If the check itself cannot be completed the call fails with collection_usage_unknown and deletes nothing.

The check reads up to 50 verification configurations. An account with more than that gets collection_usage_unknown rather than a delete the server cannot vouch for; delete the collection from the Developer Console instead.

The check is made with the account's own VerifEye credentials: one call to list the account's verification configurations, then one read for each configuration returned — up to 50 — before anything is deleted. A delete is therefore slower than the single call it looks like from the outside, and slower the more verification configurations the account has.

Input parameters:

Result:

verifeye_get_face_by_key

Looks up which onboarded face carries one of your own identifiers, and returns its faceId. Use it to turn a customer number or member id back into the faceId that verifeye_compare_face and verifeye_delete_face need. It reads nothing about the face itself: no image, no attributes, nothing biometric.

Input parameters:

Result:

A key no face holds is a normal answer, not an error: found is false and there is no faceId. That is also how to check a key is free before assigning it. A collection that does not exist is a different thing — that fails with collection_not_found, so do not treat the two alike.

verifeye_set_face_key

Attaches one of your own identifiers to a face already onboarded in a collection, so you can find it again with verifeye_get_face_by_key without remembering the faceId. No face data is changed or destroyed — this only labels it.

Input parameters:

Result:

A key belongs to exactly one face. If another face already holds it the call fails with external_key_in_use and nothing is changed — check first with verifeye_get_face_by_key, and release it with verifeye_delete_face_key if it needs to move.

verifeye_delete_face_key

Removes the link between one of your own identifiers and the face that holds it. The face itself is not deleted and stays onboarded — to delete the face, use verifeye_delete_face.

Input parameters:

Result:

faceId is required here, and is checked against the key. The Face API would accept the removal without one and unlink the key from whichever face happens to hold it — which is a different operation from the one a caller who named a face is asking for, and would quietly unlink someone else's.

verifeye_get_upload_url

Hands back a short-lived form for uploading one image to VerifEye storage, for a client that has an image but nowhere public to put it. It is registered only where the server serves uploads: a client that does not see it in tools/list has to supply a URL.

Input parameters:

Result:

Sending the image: one multipart/form-data POST to uploadUrl, with every entry of fields first, in the order returned, and the file last in a part named file. Storage refuses the upload if a field is missing, altered or sent after the file. The accepted size, 1–2000 KB, is inside the form's signature, so an over-size image is refused at ingress rather than after it is stored.

Then call one of the image tools — verifeye_identify_face, verifeye_onboard_face or verifeye_compare_face — with uploadId instead of imageUrl; supplying both is rejected. The image is deleted the moment that call returns, so an uploadId is good for one call.

Errors

A tool that fails raises an MCP error whose text is one line of JSON:

{
  "code": "collection_not_found",
  "message": "VerifEye found no such collection in the 'eu' region (404). Collections are per region, so one created in the other region is not visible here.",
  "retryable": false,
  "nextStep": "List what exists with verifeye_list_collections, in this region and in the other."
}

code is the stable half and is what to branch on — the message wording is free to change. retryable says whether repeating the same call could succeed. nextStep is absent when there is nothing useful to suggest.

Under the hood

The tools wrap the VerifEye Face API's Identify, Onboard and Compare operations and its collection endpoints, one tool per operation, with the account's API key resolved server-side from your login.

Identify requires a collection to run against, even when you are not identifying anyone. So for an anonymous analysis — verifeye_identify_face with no collectionId — the server uses a default collection of its own named mcp-default-collection, and creates it on the account the first time it is needed. Because Identify never adds a face, that collection stays empty: no face from an MCP call is ever onboarded into it, which is also why the server refuses an attempt to onboard into it. You never name or manage it yourself; it appears in verifeye_list_collections because it is a real collection on your account.

Faces you do onboard go into collections you create and name. Those are ordinary VerifEye collections, visible to the VerifEye Face API and to the Developer Console, and usable from your own backend — the MCP server holds nothing of its own beyond them.

Notes & limitations

• Estimates, not legal proof. Age is an apparent-age estimate, not a legal proof of age; gender is a demographic estimate, not a self-declared identity attribute. A face match is evidence of similarity, not an identity check on its own.
• Emotions and attention are momentary. Single-frame yes/no observations, never scores — see Reading emotions and attention.
• Honor the reliable flag. For age, treat the result as unreliable when reliable is false (the model's uncertainty exceeds 1.0). If the flag is absent there was nothing to judge the estimate by, so do not read that as reliable.
• Onboarding is the only tool that stores anything. verifeye_identify_face and verifeye_compare_face add nothing to a collection. verifeye_onboard_face stores a face template that persists until it is deleted — see Consent and retention are your responsibility.
• Deletion cannot be undone. verifeye_delete_face, verifeye_reset_collection and verifeye_delete_collection destroy face templates permanently, and verifeye_reset_collection cannot report how many it destroyed.
• Images. JPEG or PNG only, supplied as a publicly reachable URL, or uploaded with verifeye_get_upload_url where the client can reach storage — see Providing the image. Up to 4 faces per call; extra detected faces are reported in unprocessedFaceCount.
• Collection ids. 1–512 characters of letters, digits, dot, underscore and dash. Permanent — a collection cannot be renamed, only described.
• External keys. 1–512 printable ASCII characters with no spaces. One key belongs to exactly one face.
• Region & residency. region (eu/us) selects where the image is processed and where a collection lives. Your account must be authorized in the chosen region, and a collection created in one region is invisible from the other.
• Usage. Tool calls run as your VerifEye account and count against your account's usage limits. An image call is charged per face it answers about, and a call that finds no face still counts as one, because the detector ran. emotions and attention are an add-on: they do not add a second charge, they surcharge those same faces at the rate in your plan. Requesting either applies it; requesting both does not apply it twice.

Additional Resources

• Model Context Protocol specification — the open protocol the server implements.
• VerifEye Face API — the API the tools wrap. Call Identify, Onboard and Compare from your own backend for the same capabilities in the REST response's own shape.
• Authentication — API key and bearer-token authentication for the REST APIs.

Last updated: 2026-10-12