MCP

Contrie exposes a hosted Model Context Protocol server so agents can extract structured data as a tool call instead of writing HTTP client code. Streamable HTTP at:

MCP endpoint

https://www.contrie.com/mcp

Claude Code

Run this in your terminal. No key: contrie then shows “Needs authentication”.

shell

claude mcp add --transport http contrie https://www.contrie.com/mcp

Then run /mcp, pick contrie and choose Authenticate, or run claude mcp login contrie. Your browser opens, you sign in to your Contrie account and approve, and Claude Code stores the token. For a machine with no browser — CI, a container, a server — pass a key from /dashboard/keys instead:

shell — headless

claude mcp add --transport http contrie https://www.contrie.com/mcp \
  --header "Authorization: Bearer $CONTRIE_API_KEY"

Codex

Add the server once, then sign in through your browser. A Free account can use OAuth without creating an API key. If contrie is already configured, skip the add command and check that it has no API-key header or bearer setting before choosing OAuth.

shell

codex mcp add contrie --url https://www.contrie.com/mcp
codex mcp login contrie --scopes contrie:account,offline_access

~/.codex/config.toml

[mcp_servers.contrie]
url = "https://www.contrie.com/mcp"

The config-file option also needs the login command. Confirm the account shown in the browser before approving access. On September 27, Codex CLI 0.157.1 completed OAuth approval, account and verification checks, a live read and unchanged request replay with an existing Free account and no API key configured. Automatic refresh and fresh signup were not exercised. A successful login alone does not prove an existing conversation is using the token. Follow connection recovery if a tool still asks for authentication.

API-key alternative

[mcp_servers.contrie]
url = "https://www.contrie.com/mcp"
bearer_token_env_var = "CONTRIE_API_KEY"

For headless use, create a key at /dashboard/keys and supply it as CONTRIE_API_KEY in the process that starts Codex. A desktop app may not inherit your terminal's environment. Store the secret with your environment or secret manager; keep it out of prompts and source control. Choose one credential mode for this server.

claude.ai

Add Contrie as a custom connector: Customize → Connectors → Add → Add custom connector. Name it Contrie, paste the endpoint below and choose Continue. No key is needed.

MCP server URL

https://www.contrie.com/mcp

Under Authentication, choose Sign in when needed. claude.ai may preselect No sign-in, because Contrie lists its tools without an account. That choice works too: the first time Claude uses a tool that needs your account, it shows Connect, which opens Contrie's sign-in, where you can also create an account. Verified on 2026-09-24: a new account signed up this way and its first extraction was charged Free credits.

JSON config (Cursor and other MCP clients)

For clients that read a JSON configuration file with a remote url. Replace ck_live_... with a key from /dashboard/keys. Claude Desktop is not one of them: its configuration file runs local servers only, and it adds remote servers as custom connectors that sign in instead of sending a key, as in claude.ai. Claude Desktop's own sign-in has not been verified separately. See Connect with your Contrie account.

JSON

{
  "mcpServers": {
    "contrie": {
      "url": "https://www.contrie.com/mcp",
      "headers": {
        "Authorization": "Bearer ck_live_..."
      }
    }
  }
}

Tools

Tool	Input	Returns
contrie_account	{}	Your credits, next UTC reset and current restrictions. Zero extraction credits. Advisory only; reserves no capacity. Check before new work and avoid a polling loop.
contrie_extract	{ url, extract?, schema?, maxAge?, render?, idempotencyKey? }	The same JSON response as /api/v1/scrape, as a text content block. Marked `isError` when the service returned an error code. A rate-limiting source's wait is the REST `Retry-After` header, REST only by design. Over MCP an origin rate limit arrives as SOURCE_REFUSED with no wait: use a bounded backoff before one or two retries. REST's `format: "both"`, `options.timeout` and `options.waitFor` are not tool arguments.
contrie_read	{ url, maxAge?, render?, idempotencyKey? }	The same JSON response as the REST API, serialized in a text content block: `data: null`, `markdown`, and metadata/evidence. A successful read costs 1 credit and a failed one 0; a successful rendered read adds 2.
contrie_verify	{ data, url \| html (+ baseUrl?) \| text }	A field-by-field grounding report for data from any source — see Verify. The same source bytes and data give the same verdict.
contrie_watch	{ url, extract?, schema?, every?, webhookUrl? }	A recurring monitor and its first result. Every run with an accepted answer is charged like one extraction until you stop the monitor, so an hourly monitor can make up to 24 charged runs a day. Runs depend on current service capacity.
contrie_monitors	{}	Your active monitors, with each id. Charges no credits.
contrie_unwatch	{ id }	Stops your monitor: no further scheduled runs or charges, though a run already in progress can finish. Returns the monitor with `active: false`; history stays readable with contrie_changes. Charges no credits.
contrie_changes	{ id, before?, eventId? }	Latest 20 events for your own monitor. Pass nextCursor as before for older history, or eventId to recover one exact event; do not combine them. Stopped monitors remain readable. Zero extraction credits.

Recover a request, then repeat deliberately

Give contrie_extract or contrie_read a unique idempotencyKey (8–200 visible ASCII characters), and keep its original arguments. If the response is lost, call the tool again with the same arguments and key. A completed response stays recoverable for 24 hours without another extraction or charge. It retains the original source time and signature; recovery does not fetch fresh information. Check both isError and the result's decision.

Wait briefly before checking an in-progress request. Conflicting inputs, expired responses and unknown outcomes return explicit errors; do not replace the key automatically. A new question or deliberate fresh check needs a new key. Without a key, each tool call starts separate work. Authentication is required. The hosted tools support this argument; refresh your client's tool list after an update. It does not apply to monitor creation or streaming REST calls.

Optional field verification pilot

When enabled by the operator, the catalog also includes contrie_check_fields to check explicit entity, field and context relationships in supplied HTML, and contrie_verification to recover or list your saved runs. These share the browser workspace's pilot limits and charge no extraction credits. They do not change contrie_verify, which still checks text presence. Refresh your client's tool list before use.

This mode requires HTML the caller already has; it does not fetch the source URL or accept markdown as equivalent evidence. Keep the required UUID v4 submission key and original input. A completed refusal is a saved decision with withheld data, not an operational tool error. Follow the agent field-check workflow for examples, recovery and retention.

Authentication

Sign in with your Contrie account (below), or pass an API key as an Authorization header on the MCP connection, same as the REST API. Without either, clients can initialize and list tools, and a client on protocol version 2026-07-28 can call server/discover. Only an exact recorded request succeeds, and only through contrie_extract — its URL and prompt must match one of the pairs in /llms.txt, with JSON format, and with the recorded schema where that page lists one. Recorded runs are JSON, so contrie_read always needs sign-in or a key. See Authentication for both.

Never put a key in a URL
Never paste a key into an agent chat — pass it as a connection header

First call, reconnect and account switching

After sign-in, ask your agent to call contrie_account with no arguments. This checks the active connection and costs zero extraction credits. Then try contrie_read with {"url":"https://example.com/","render":"never"} for a live page read (1 credit on success). Seeing a server or its tool list does not prove account access: discovery is available before sign-in.

Authentication required after login: reconnect or reload the MCP connection in the client holding the conversation, then retry the account check. In Claude Code, open /mcp, select contrie and choose Reconnect; use Authenticate or Re-authenticate if offered. In Codex, run codex mcp login contrie --scopes contrie:account,offline_access if needed, then reload the connection. If your client has no reload action, restart it and resume the conversation, or start a new session. Browser sign-in does not by itself refresh every running connection.
Expired connection: a client can renew a token when it has a usable refresh token. If renewal fails, sign in again through that client; no API key is required for OAuth recovery. For claude.ai or Claude Desktop, reconnect the custom connector in its connector settings. A 403 insufficient-scope response requires approving the contrie:account permission, not repeated tool calls.
Switch accounts: use codex mcp logout contrie or claude mcp logout contrie, then sign in again. Select the intended Contrie account in the browser before approving. If the browser retains the previous account, sign out of Contrie there first. Reconnect the conversation and repeat the account check. Clearing client credentials does not immediately revoke an already-issued token on every device.
Switch between a key and OAuth: remove the previous credential source from this server's client configuration before enabling the other. A configured Authorization header or bearer token can take precedence over browser sign-in; a stored OAuth token can take precedence over a helper-provided header. Do not delete your account or revoke unrelated keys to repair a connection.

After reconnection, recover an interrupted extract/read with the same inputs and idempotencyKey, if one was supplied. Do not create a new request identity merely to get past an authentication error. If recovery still fails, report the client/version, time and error code to support; never send a token, API key or browser authorization callback URL.

Connect with your Contrie account

OAuth support requires a client and authorization server that issue a resource-bound token for https://www.contrie.com/mcp. The server requires a Clerk-issued JSON Web Token (JWT) with this exact audience, the configured Clerk issuer, and the contrie:account permission. This grants the same extraction, verification and monitor access as an account API key, subject to your plan and credits. Opaque OAuth tokens are unsupported. Verified end to end with Claude Code on 2026-09-21: it discovered the challenge, identified itself, completed the browser flow and called an authorized tool with the resulting token. Verified with a claude.ai custom connector on 2026-09-24, from a new account's sign-up to its first extraction. Codex CLI 0.157.1 also completed an existing Free account's sign-in, live read and replay without an API key on 2026-09-27; automatic token refresh remains unverified. Other clients' OAuth flows, including Claude Desktop's, are not yet verified.

Missing or invalid credentials receive HTTP 401 with a protected-resource challenge. A valid token without the account permission receives HTTP 403 with an insufficient-scope challenge. JWT verification does not provide immediate revocation; already-issued tokens can remain valid until expiry. Discovery is published at /.well-known/oauth-protected-resource/mcp.