Cogneris, inside your code editor.

What it is

A Model Context Protocol server in front of the same platform your API keys already reach.

• An MCP endpoint, not a second product — every tool call goes to the same Cogneris services the REST API uses. Same tenant, same metering, same audit trail.
• Built for writing integrations — the assistant searches the docs, reads the exact contract of a route with code in Node, Python, C# and curl, then creates the API key and webhook your code needs.
• 53 tools in eight areas — account, docs and API reference, API keys, webhooks, classifiers, workflows and their runs, Build AI, and PDF fill. 21 read tools carry mcp.read and 10 write tools carry mcp.write; API key management, webhook management and Build AI have scopes of their own.
• Stay connected with a developer token — generate it in the Cogneris platform, paste it once, and your editor keeps it in its own secret storage for up to 90 days.
• Any MCP client — VS Code, Cursor and Claude Code are the three we document below; anything that speaks streamable HTTP works the same way.

Watch it in VS Code

A four-minute walkthrough, recorded in production: set up the server, then ask GitHub Copilot for an API key, Python code that extracts and classifies documents, and a webhook with a verified signature.

• Cogneris in VS Code: MCP, API keys, Python code and webhooks — in English
• Cogneris no VS Code: MCP, chave de API, código Python e webhooks — in Brazilian Portuguese

Server URL

One URL per production region — use the one your tenant lives in. Europe is the default region for new tenants.

Your tenant region is pinned at sign-up and matches the REST host you already use (api-eu; the US region and api-us are paused since 2026-10-27) — see Environments. The MCP page in the platform shows the right URL for your tenant. The JSON-RPC endpoint is the root path /, not a sub-path.

Generate a developer token

The recommended way in: one token, scoped and expiring, that keeps your editor connected.

• Where — in the Cogneris platform, open Vision → MCP. The page shows your server URL, ready-to-paste configuration for each editor, and the token generator.
• What you choose — a name that says where the token is used, a validity of 30 or 90 days, and its scopes. mcp.read and mcp.write are ticked by default; add apikeys.manage or webhooks.manage only if the assistant should manage keys or webhooks.
• Shown once — copy the token when it appears; it is not shown again. Generate a new one if you lose it.
• Tied to you — every action taken with the token is recorded against your user. Revoke it from the same page when you no longer need it.

Connect your editor

Three editors, one server. Swap the URL for your region.

VS Code

Put this in .vscode/mcp.json. The token is a password input: VS Code asks for it once, keeps it in its secret storage, and never writes it to the file — so the file is safe to commit.

{
  "inputs": [
    {
      "id": "cogneris-token",
      "type": "promptString",
      "password": true,
      "description": "Cogneris developer token"
    }
  ],
  "servers": {
    "cogneris": {
      "type": "http",
      "url": "https://mcp-eu.cogneris.ai/",
      "headers": { "Authorization": "Bearer ${input:cogneris-token}" }
    }
  }
}

Cursor

Put this in ~/.cursor/mcp.json and replace the placeholder with your token. This file holds the token in plain text, so keep it out of any repository.

{
  "mcpServers": {
    "cogneris": {
      "url": "https://mcp-eu.cogneris.ai/",
      "headers": { "Authorization": "Bearer <YOUR_COGNERIS_TOKEN>" }
    }
  }
}

Claude Code

One command registers the server; replace the placeholder with your token.

claude mcp add --transport http Cogneris https://mcp-eu.cogneris.ai/ \
  --header "Authorization: Bearer <YOUR_COGNERIS_TOKEN>"

A custom MCP client

The server is stateless, so a single POST lists the catalog. Send both content types in Accept — replies are SSE-framed. Then call cogneris_whoami to confirm which tenant, user and scopes the connection carries.

curl -sS https://mcp-eu.cogneris.ai/ \
  -H "Authorization: Bearer $COGNERIS_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Browser sign-in (OAuth)

The alternative to a token: sign in through the browser, for sessions of up to 1 hour.

• Configure the URL without a header — a call without credentials answers 401 with a WWW-Authenticate header pointing at the server's metadata, which is the signal an MCP client uses to start sign-in.
• Authorization code with PKCE — the client sends you to the Cogneris sign-in page for your region (sso-eu.cogneris.ai or sso-us.cogneris.ai) and exchanges the code for a short-lived bearer token. There is no client secret in your configuration.
• The session lasts 1 hour — that cap is a security control of the Cogneris sign-in. To stay connected for days, use a developer token instead.
• Covers the two MCP scopes — browser sign-in grants mcp.read and mcp.write. The API key, webhook management and Build AI tools need a developer token that carries their scopes.
• Discover before you configure — GET /.well-known/oauth-protected-resource is anonymous and returns the resource identifier (the server's own https:// URL), the authorization server and the supported scopes, per RFC 9728. Read it rather than hardcoding.

Scopes

A tool whose scope your credential lacks is not listed, and refuses to run if called.

Tool catalog

53 tools, grouped by area. The names are exactly what tools/list returns; the scope column is what the credential must carry.

Account and usage

Who the connection acts as, and what the tenant has consumed.

Docs and API reference

So the assistant in your editor writes code against the real API instead of guessing it.

API keys

Keys for your own code. These tools are listed only when the developer token carries apikeys.manage.

Webhooks

Endpoints that receive Cogneris events. The event catalogue needs mcp.read; everything else needs webhooks.manage.

Classifiers

Your own document types — the ones shown as templates in the Cogneris app.

Workflows

Write a workflow graph from a description: read the schema, validate, save a draft, publish when you confirm. No Build AI credits.

Workflow runs

Try a published workflow on real documents and see what each step decided.

Build AI

Let Cogneris draft the whole process — workflow, classifier and templates — from your description. Listed only when the developer token carries builder.run; every step states its cost.

PDF fill: templates, sources, jobs and artifacts

Write-back: stamp extracted data into a PDF template and download the result.

Transport & discovery

Stateless streamable HTTP. Worth knowing if you are writing the client yourself.

• Stateless by design — there is no Mcp-Session-Id to carry. Every request stands on its own, which is what lets the service scale to zero between calls.
• JSON-RPC at the root — POST to /. There is no /mcp sub-path; a client configured with one gets a 404.
• Responses are SSE-framed — the reply comes back as text/event-stream, so the request must advertise Accept: application/json, text/event-stream.
• A missing or rejected credential is a 401 — with WWW-Authenticate: Bearer resource_metadata="…", never an empty tool list.
• Two anonymous discovery documents — /.well-known/mcp.json publishes the protocol version, the server identity and the supported scopes; /.well-known/oauth-protected-resource publishes the RFC 9728 metadata. Neither needs a token.
• Health is public too — GET /health answers without credentials, which is what the regional status probes read.

Before you wire it up

Behaviours that surprise people once an agent is driving.

• API keys are sandbox by default — cogneris_apikeys_create makes a sandbox key unless you explicitly confirm a production one. Keys created from the editor never carry apikeys.manage, mcp.read or mcp.write.
• Secrets are handed out once — a new API key, webhook signing secret or rotated secret appears in one answer only. The assistant is told to write it to your git-ignored .env and never repeat it in chat, code or commits.
• Fill jobs cost money — cogneris_jobs_create consumes credits on your plan. An agent looping over a folder spends real budget, so cap it in the prompt as well as in the tenant cost cap.
• Creating is not idempotent — creating a classifier, adding samples, registering a template, uploading a source, starting a fill job, or creating a webhook or an API key each make a new record per call. A retried tool call is a duplicate, not a no-op. Workflow writes, workflow runs and the Build AI steps that cost credits are the exception: a retry with the same input is answered once.
• Publishing asks first — new runs use a published workflow version, so the assistant shows you the graph and publishes only after you say yes. Deleting a workflow and promoting it from sandbox are not available over MCP.
• Build AI spends credits and needs an admin — the plan costs 10 to 30 credits and a revision 5 to 15, including the automatic research and revisions. It runs on production developer tokens that carry builder.run, owned by a tenant administrator; a sandbox token is refused.
• Uploads cap at 10 MB decoded — that is the size after base64 decoding, so budget roughly 7.5 MB of file. Larger sources go through the REST upload path instead.
• Signed URLs expire in 5 minutes — fetch the artifact when you get the URL. Storing it for later is storing a dead link.
• Usage ranges are UTC and half-open — to must be strictly greater than from; reversed or equal ranges are rejected rather than silently clamped.