Curation MCP

The Curation API speaks the Model Context Protocol,
so an AI client can read your deals and the targeting vocabulary, validate a
deal request, create one and edit one, directly. It is the same API, the
same key and the same permissions: each tool is one endpoint, a successful
call returns that endpoint's body, and a failed one returns its error
message.

Endpoint

https://api.sovrn.com/sovrnos/v1/mcp

Authenticate exactly as you do for REST: send your key in the x-api-key
header. There is no separate sign-in, no OAuth and no token to refresh; see
Authentication.

📘

One key, one account

A tool can only reach what your key can reach. Deals are scoped to your
account, so list_deal_requests returns your deal requests and nobody
else's, and a read-only key is refused by the three write tools with
Insufficient scope.

🚧

Browser-based clients cannot connect

A request that carries an Origin header is refused, which keeps this
endpoint out of reach of web pages. Browsers attach one, so a client that
runs in a browser cannot connect.

Configure your client

Claude Code

claude mcp add --transport http curation https://api.sovrn.com/sovrnos/v1/mcp \
  --header "x-api-key: $SOVRN_API_KEY"

Then claude mcp list shows the connection.

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json
(one project):

{
  "mcpServers": {
    "curation": {
      "url": "https://api.sovrn.com/sovrnos/v1/mcp",
      "headers": {
        "x-api-key": "${env:SOVRN_API_KEY}"
      }
    }
  }
}

Cursor resolves variables in url and headers, so ${env:SOVRN_API_KEY}
keeps the key out of the file. Set SOVRN_API_KEY in the environment Cursor
is started from. A project's configuration file is often committed to source
control, and a key written into it would be committed with it.

🚧

Treat the key as a secret

A write key can create and edit deals on your account, and a read-only key
can read them. Do not commit a configuration file with the key inline, and
do not paste it into a chat window. Prefer an environment variable, as shown
above.

Tools

The four read tools and validate_deal_request are marked readOnlyHint.
create_deal_request and update_deal_request are marked as what they
are: not read-only, and in the case of an edit, destructive.

🚧

Approval is your client's setting

Whether a tool runs without asking you first is decided by your client and
how it is set up, not by this API, and some clients run tools without
asking. Check that setting before you connect a key that can create or
edit deals.

On success, every tool returns the REST endpoint's body both as text and as
structured content, so a client that supports structured content receives the
same object the REST endpoint returns. Each tool but create_deal_request also
publishes a result schema. The create publishes none on purpose: a 201
means the deal exists, and a result a client could read as a failure would
invite a second attempt at a deal you already have.

Validate, then create

validate_deal_request and create_deal_request take the same fields. The
first runs every check the second does (the schema, the DV360 field
requirements, the targeting caps) and stops before anything is created, so
an error from it is the error a create would have given you. Ask for a
validation first, read the result, and only then create:

Validate this deal request: CTV video, $12.50 fixed floor, US only,
buyer rtbhouse seat 4471, starting the first of next month.

Because a create is not reversible from this API (there is no delete),
create_deal_request is described to your client as something to confirm
with you before it runs. Whether your client acts on that is its own
setting, so validating first is the checkpoint you control.

Editing works the same way as the REST endpoint: send only the fields you
are changing. update_deal_request needs the dealRequestId and the
change; description: null clears the description, and a targeting array
replaces the whole of the previous one rather than adding to it. See
Editing a deal for the other rules.

update_deal_request can also set the deal's status. Whether to offer that
is what statusSettable says: get_deal_request returns it, and a status
change belongs only on a deal where it is true (see
Deal lifecycle).

Errors

A failed tool call comes back as an error result whose text is the message the
equivalent REST call would have returned, the same wording described on the
Errors page. For example, asking for more than 100 deal requests
returns:

querystring/limit Too big: expected number to be <=100

A key without write permission is refused by validate_deal_request,
create_deal_request and update_deal_request with Insufficient scope,
before the request body is validated, exactly as the REST endpoints refuse
it.

A wrong key, or one without access to the Curation API, fails the connection
before any tool runs, so you will not see a tool error. The endpoint answers
401 or 403, and clients report that in different ways: as a request to
sign in, as an OAuth error, or as a 404.

🚧

There is no sign-in

This endpoint authenticates with your API key and nothing else. Whatever
your client reports, do not look for a login: check the x-api-key value
in your configuration.

Rate limit

MCP traffic counts against the same budget as REST (see
Introduction). The budget counts HTTP requests, and
connecting costs several of them before any tool runs: up to four for a
client using the older protocol revision, two for one on the current
revision. Each tool call is one more. At 15 requests a minute that is
material, so a client that reconnects frequently uses noticeably more of the
budget than its tool calls alone suggest.