essentras-mcp

# Essentras MCP server

Buy press coverage from an AI agent.

Essentras is a marketplace for paid media placements. This MCP server makes the catalogue
machine readable end to end: an agent can search 3,800+ vetted outlets by budget, domain
authority, geography, topic and link policy, price a basket, and hand the buyer a checkout
link. No account, no API key, nothing to negotiate.

Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as
`com.essentras/placements`.

## Quick start

Add this to any MCP client (Claude Desktop, Claude Code, Cursor, VS Code):

```json
{
  "mcpServers": {
    "essentras": {
      "type": "http",
      "url": "https://essentras.com/api/mcp"
    }
  }
}
```

Then ask for what you want:

> Find US tech outlets under $400 that give dofollow links, then price the best three.

> I have $2,000 for fintech press in the UK. What can I get?

> What does a placement on Business Insider cost, and how long does it take?

## Tools

| Tool | What it does |
| --- | --- |
| `search_outlets` | Search by `max_price`, `country`, `region`, `language`, `topic`, `min_da`, `dofollow`, `indexed`, with sorting and paging. Returns offers with a fixed USD price, turnaround, link policy and a stable id. |
| `get_outlet` | Full detail for one outlet by id. |
| `quote_placements` | Prices a basket. Returns line items, any volume discount, the final total and a `checkout_url`. Charges nothing and creates no order. |

All three are annotated read-only and idempotent.

## The agent never pays

This is a design decision, not a limitation waiting to be removed.

The server holds no payment method and cannot take money. `quote_placements` returns a
`checkout_url`; the buyer opens it, sees the same basket at the same total, and pays on
essentras.com. So the worst case for someone who hands an agent too much trust is a basket
they did not want, never a charge they did not authorize.

A capability the server does not have is a stronger guarantee than an instruction a model
might ignore.

## The quote is the price

`quote_placements` exists rather than expecting you to add up list prices, because the
basket total is not the sum of its parts: volume tiers apply at 3 and 5 placements. The
page, the REST API, the MCP server and the charge all read one pricing function, so the
number an agent reports is the number the buyer is charged.

Billing is at checkout, not on publication. If the placement does not publish, or the
stated turnaround is missed, the order is refunded.

## Plain HTTP

Everything the MCP server does is also a REST endpoint, described by OpenAPI 3.1.

```bash
curl "https://essentras.com/api/agent/v1/outlets?country=US&dofollow=true&max_price=400&limit=3"
```

```bash
curl -X POST https://essentras.com/api/agent/v1/quote \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"id":"business-insider"},{"id":"msn"}]}'
```

See [`examples/quickstart.sh`](examples/quickstart.sh) for a runnable walkthrough.

| Endpoint | |
| --- | --- |
| [`/api/agent/v1`](https://essentras.com/api/agent/v1) | Service description and checkout model |
| [`/api/agent/v1/openapi`](https://essentras.com/api/agent/v1/openapi) | OpenAPI 3.1 |
| [`/api/agent/v1/feed`](https://essentras.com/api/agent/v1/feed) | Product feed, JSONL, Agentic Commerce Protocol shape |
| [`/.well-known/agent.json`](https://essentras.com/.well-known/agent.json) | Discovery manifest |
| [`/llms.txt`](https://essentras.com/llms.txt) | What we sell, in prose |

## Protocol support

Streamable HTTP, dual era on purpose. The server implements the `2026-07-28` revision
(stateless, `server/discover`, per-request `_meta`, `resultType`, cache hints) **and** the
earlier `initialize` handshake, because a large share of clients in the wild still open the
old way. Unsupported versions get a proper `UnsupportedProtocolVersionError` with the list
of versions we do speak, so a client can retry rather than guess.

## Limits and honest notes

- Read and quote are public and rate limited per IP. There is nothing to gate: everything
  the API returns is already visible on the website.
- JSON-RPC batches are capped (20 messages, 5 of them tool calls). An unbounded batch is a
  cheap way to buy a lot of someone else's database time.
- One outlet per order, so `quote_placements` takes no quantity. The checkout handoff
  cannot express it, and quoting a basket the cart cannot reproduce would be worse than
  not supporting it.
- Most placements publish as standard editorial articles with no sponsored label. A
  minority carry a sponsored or discreet disclosure, and every offer states which under
  `link.disclosure`. Do not assume the whole catalogue is one or the other.
- The catalogue is what it is: strong in business, tech and finance, thinner on some
  tier-one US names. Search it rather than assuming an outlet is there.

## Links

- Documentation: [essentras.com/agents](https://essentras.com/agents)
- Marketplace: [essentras.com/publishers](https://essentras.com/publishers)
- Contact: [essentras.com/contact](https://essentras.com/contact)

## License

MIT. See [LICENSE](LICENSE).