Skip to main content

Connect your editor to the MCP server

The Cogneris MCP server puts the Cogneris platform inside the AI assistant of your code editor. Once it is connected, the assistant can search the Cogneris documentation, read the exact contract of any API route, create API keys and webhooks, train classifiers and run fill jobs — on your tenant, with the same audit trail as the REST API.

It is an endpoint of the platform you already use, not a second product: every tool call reaches the same Cogneris services as the REST API, with the same tenant, the same metering and the same audit trail.

Cogneris MCP: Cogneris in VS Code: MCP, API keys, Python code and webhooks Watch on YouTube

Server URL​

One URL per production region. Use the region your tenant lives in — the one of the API host you already call (api-eu, or api-us for a tenant in the United States). New tenants are created in Europe.

RegionMCP server URL
Europe (default)https://mcp-eu.cogneris.ai/
United Stateshttps://mcp-us.cogneris.ai/

The JSON-RPC endpoint is the root path /. There is no /mcp sub-path: a client configured with one gets a 404.

Generate a developer token​

The developer token is the recommended way in: one credential, scoped and expiring, that keeps your editor connected for up to 90 days.

  1. In the Cogneris platform, open Vision → MCP. The page shows your server URL, configuration ready to paste for each editor, and the token generator.
  2. Give the token a name that says where it is used (for example "VS Code — laptop").
  3. Choose a validity of 30 or 90 days.
  4. Choose the scopes. mcp.read and mcp.write are ticked by default. Add apikeys.manage and webhooks.manage only if the assistant should manage API keys and webhooks.
  5. Copy the token. It is shown once — generate a new one if you lose it.

Every action taken with the token is recorded against your user. Revoke it from the same page when you no longer need it.

The developer token is not an API key

The token connects your editor to the MCP server. The code you ship calls the REST API with an API key — which the assistant can create for you.

Add the server to your editor​

Replace the URL with the one of your region.

Create .vscode/mcp.json in your project. 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 and every developer on the team gets the same configuration.

.vscode/mcp.json
{
  "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}" }
    }
  }
}

Then open Copilot Chat, switch to Agent mode and check that the Cogneris tools are enabled in the tools picker. MCP: List Servers in the command palette shows whether the server is running.

Check the connection​

Ask the assistant:

Who am I connected as on Cogneris?

It calls cogneris_whoami and answers with your tenant, user and e-mail, how you signed in, sandbox or production, the granted scopes and the API base URL your code should call. If that works, everything else will.

Browser sign-in instead of a token​

Configure the URL without the Authorization header. The server answers the first call with 401 and a WWW-Authenticate header that points to its metadata — the signal an MCP client uses to open the Cogneris sign-in page of your region in the browser (authorization code with PKCE; there is no client secret in your configuration).

  • The session lasts 1 hour, a security control of the Cogneris sign-in. To stay connected for days, use a developer token.
  • Browser sign-in grants mcp.read and mcp.write. The API key and webhook tools need a developer token that carries their scopes.

Scopes​

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

ScopeWhat it unlocks
mcp.readEvery listing and lookup: account, usage, docs and API reference, classifiers, fill templates and jobs, the webhook event catalog.
mcp.writeCreating classifiers, adding samples and training them, registering fill templates, uploading sources and starting fill jobs.
apikeys.manageListing, creating and revoking API keys. Never implied by mcp.write.
webhooks.manageManaging webhook endpoints and deliveries. Never implied by mcp.write.

What the assistant can do​

35 tools in six areas. You never call them by name — you describe what you want and the assistant picks them.

AreaToolsWhat the assistant does with them
Account and usagecogneris_whoami, cogneris_usage_summaryConfirms who the connection acts as; reports documents, pages and AI tokens per day and per document type.
Docs and API referencecogneris_docs_search, cogneris_docs_get, cogneris_api_operations, cogneris_api_referenceSearches this documentation and reads the exact contract of a route, with ready-to-run Node, Python, C# and curl that read the key from COGNERIS_API_KEY.
API keyscogneris_apikeys_list, cogneris_apikeys_create, cogneris_apikeys_revokeCreates keys with only the scopes your code needs — sandbox by default.
Webhookscogneris_webhooks_event_types, cogneris_webhooks_create, cogneris_webhooks_test, cogneris_webhooks_deliveries_list, cogneris_webhooks_deliveries_replay and moreRegisters endpoints, returns the signing secret once with receiver code, sends test deliveries, inspects and replays failed ones.
Classifierscogneris_classifiers_create, cogneris_classifiers_add_samples, cogneris_classifiers_train, cogneris_classifiers_status and moreCreates your own document types from sample files and trains them.
PDF fillcogneris_templates_register, cogneris_sources_upload, cogneris_jobs_create, cogneris_artifacts_download and moreStamps extracted data into a PDF template and downloads the result.

The server also ships two ready-made prompts your editor lists in its prompt menu (in VS Code, type / in the chat): Integrate the Cogneris API into this project and Create and train a Cogneris classifier.

Classifiers are not fill templates

Classifiers are your own document types — the ones the Cogneris app shows as templates. Fill templates are PDF layouts a fill job stamps data into. When you ask "what templates do I have?", the answer you want comes from the classifiers.

Before you let an agent drive​

  • API keys are sandbox by default. A production key is created only when you explicitly confirm it. 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 a single answer. The assistant is told to write it to your git-ignored .env and never repeat it.
  • Fill jobs cost credits. An agent looping over a folder spends real budget — cap it in the prompt as well as in the tenant cost cap.
  • Creating is not idempotent. Each create call makes a new record; a retried call is a duplicate.
  • Uploads cap at 10 MB decoded (about 7.5 MB of file). Larger files go through the REST upload path.
  • Signed download URLs expire in 5 minutes. Fetch the file when you get the URL.

Troubleshooting​

SymptomCause and fix
404 on every callThe URL has a path such as /mcp. Use the root: https://mcp-eu.cogneris.ai/.
401 UnauthorizedMissing, expired or revoked token. Generate a new one in Vision → MCP.
The API key or webhook tools are missingThe token lacks apikeys.manage or webhooks.manage, or you signed in through the browser. Generate a token with those scopes.
406 Not Acceptable from your own clientSend Accept: application/json, text/event-stream.
The assistant writes code without calling CognerisMake sure the chat is in Agent mode and the Cogneris tools are enabled, then mention Cogneris in the prompt.

Next​