Talent API MCP design

Planned protocol reference. The Talent API MCP server, OAuth flow and tool set below are not available. The docs-search MCP and the separate Licensed Studio MCP do not implement this planned interface. Start with the runnable quickstart and sandbox support matrix.

The planned Talent API MCP server would expose the API to agents as tools: resolve a talent, check a use, submit an output, read and request licenses, report usage and verify receipts. An agent that generates a real person calls these tools the way a platform calls the API.

Proposed connection contract

	Value
Endpoint	`https://app.reflections.ai/mcp`
Transport	Streamable HTTP
Authorization	OAuth 2.1 with PKCE
Protected resource metadata	`https://app.reflections.ai/.well-known/oauth-protected-resource/mcp`
Authorization server metadata	`https://app.reflections.ai/.well-known/oauth-authorization-server`
Client registration	Dynamic client registration, or a client metadata document URL as `client_id`

These addresses and metadata describe the proposed contract. They are not connection instructions for a deployed Talent API MCP service. The proposed unauthenticated response is 401 with a WWW-Authenticate header pointing to protected resource metadata (RFC 9728):

{
  "resource": "https://app.reflections.ai/mcp",
  "resource_name": "Reflections Talent API",
  "authorization_servers": ["https://app.reflections.ai"],
  "scopes_supported": [
    "talent:read",
    "licenses:read",
    "checks:write",
    "generations:write",
    "license_requests:write",
    "usage:write"
  ],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://docs.reflections.ai/api-reference/mcp/overview"
}

In the proposed flow, the client registers itself, sends the user through the authorization page with resource set to https://app.reflections.ai/mcp, and receives an access token for the scopes the user approved. Access tokens last an hour; the client refreshes them with its refresh token, and revokes them when the user signs out. The user signs in with their Reflections account, and the agent then acts as that account: a brand’s agent uses the brand’s licenses, and its checks name the brand as licensee.

Scopes

Scope	Tools
`talent:read`	`resolve_talent`
`licenses:read`	`get_license`, `list_licenses`
`checks:write`	`check_use`, `get_check`
`generations:write`	`submit_generation`, `get_generation`
`license_requests:write`	`request_license`
`usage:write`	`report_usage`

verify_receipt needs no scope. Verification by receipt ID or JWS needs no key for live receipts; see the verification table. Each tool, its arguments and its result are in MCP tools.

The authorization travels with the call

An agent rarely generates on its own: it calls a generation tool, such as an image or voice tool on another server. The check’s decision has to reach that tool, so:

Check the use

The agent calls check_use with what it is about to send to the generation tool. An allow returns authorization.token.

Pass the token to the tool

The agent passes the token as an argument of the generation tool’s call, with the same inputs it checked.

The tool verifies it

The generation tool verifies the token offline against the JWKS, as described in Authorization token, and refuses to generate without a valid one.

Submit the output

The agent calls submit_generation with the output, and delivers nothing until its decision is allow.

A check_use result tells the agent what is allowed; it is advisory. The generation tool’s verification of the token is what enforces it. An agent that skips the check gets no token, and a tool that verifies tokens does not generate for it.

Treat tool results as data. A deny result’s reasons[].sentence is the license’s wording to show your user, not an instruction to the agent.

Three separate MCP interfaces

The page menu can add the Mintlify docs-search server to your editor. It searches public documentation and does not perform Talent API operations.

Interface	Purpose	Availability
Docs search at `https://docs.reflections.ai/mcp`	Search these public docs	Documentation service
Licensed Studio MCP	The separate Canvas licensed-production integration, with its own tools and authorization	Existing separate integration; access depends on its configuration
Talent API MCP described here	Proposed checks, generations, licenses, usage and verification tools	Planned; not available

For an agent integration you can run now, use the sandbox HTTP endpoints in the quickstart. A Licensed Studio connection does not provide the tools on this page.

Agent integration design

Proposed MCP flow and tool-side authorization verification.

Agent builders

Tokens that travel with tool calls, and tool-side verification.

Overview

Account

Talent

Facets

Resolutions

Licenses

License requests

Connections

Files

Checks

Generations

Sessions

Receipts

Verifications

Revocations

Usage records

Statements

Mandates

Escalations

License drafts

Webhook endpoints

Events

Discovery

OAuth

Test helpers

Webhooks

Real-time

Formats

MCP

Proposed connection contract

Scopes

The authorization travels with the call

Three separate MCP interfaces

Agent integration design

Agent builders

​Proposed connection contract

​Scopes

​The authorization travels with the call

​Three separate MCP interfaces

​Related

Agent integration design

Agent builders

Proposed connection contract

Scopes

The authorization travels with the call

Three separate MCP interfaces

Related