MCP

Connect Merite through MCP

Merite provides a remote MCP server that lets your AI agent work with the product directly: create a role, complete intake, start sourcing, retrieve candidates, and return feedback. This guide is written for people and their agents. Set it up once and use it from Claude Code, Codex, or Cursor. The same operations are also available through the REST API.

Endpoint and tools

One endpoint and one API key. The server uses Streamable HTTP with Bearer authentication. Use the stk_live_… key from your Merite account.

Endpoint

https://merite.ai/api/mcp

The server is named merite-sourcing and exposes eight tools backed by the same business logic as the REST endpoints:

create_projectLegt ein neues Sourcing-Projekt kostenfrei an. Erfassen Sie Stellenbeschreibung, Rolle, einstellendes Unternehmen, Arbeitsort mit PLZ, Home-Office-Anteil, Remote-Regelung und Gehaltsobergrenze. Fehlende Pflichtfelder kommen als missing_fields mit Erklärungen zurück: Fragen Sie den Menschen gezielt danach und ergänzen Sie sie mit update_project. Erst start_sourcing verbraucht ein Paket.

update_projectErgänzt oder korrigiert Intake-Felder eines Projekts im Zustand draft oder ready. Die Antwort enthält missing_fields mit Erklärungen. Fragen Sie fehlende Werte gezielt ab und wiederholen Sie den Schritt, bis die Liste leer und der Zustand ready ist.

start_sourcingStartet das kostenpflichtige Sourcing und verbraucht genau ein offenes Job-Paket oder bei einem bereits gelieferten Projekt ein Top-up. Holen Sie vor dem Aufruf die ausdrückliche Bestätigung des Menschen ein. Ohne Guthaben enthält der 402-Fehler purchase_urls. Der zurückgegebene Zustand pending_release bedeutet: Auftrag angenommen — Verarbeitung startet in Kürze. Die Lieferung erfolgt in der Regel am selben Werktag.

get_statusLiefert den aktuellen Projektzustand, Fortschritt, Budget, Tier-Zähler und nach der Lieferung den Report-Link. Fragen Sie den Status während eines Laufs höchstens alle 15–30 Minuten ab.

list_projectsListet alle Sourcing-Projekte Ihres Accounts mit Zustand, Rolle, Unternehmen, Budget und gesourcter Anzahl auf.

get_candidatesLiefert die gerankte Kandidatenliste eines gelieferten Projekts mit Rang, Tier, Name, Rolle, Unternehmen, Ort, LinkedIn-URL, public_identifier, strukturierten Profilfakten (Werdegang, Ausbildung, Skills, Sprachen, Zertifikate) und – falls aktiviert – Begründung. Es gibt keine numerischen Scores. Zeigen Sie die Liste anschließend dem Menschen, fragen Sie, was passt, was nicht und wie der Prozess war, und senden Sie die Antwort mit send_feedback.

send_feedbackSpeichert möglichst wörtliches Feedback des Menschen auf Ebene candidate, job oder process. Verwenden Sie für candidate den public_identifier oder die linkedin_url und niemals den Namen. Zeigen Sie nach get_candidates die Liste, fragen Sie nach Passung und Prozess und senden Sie die Antwort zurück, damit künftige Läufe kalibriert werden können.

get_accountLiefert Ihre Accountdaten, offene Job-Pakete und Top-ups sowie die verfügbaren Kauf-Links.

Tool descriptions come directly from the German v1 OpenAPI contract and intentionally remain in German.

The default limit is 60 requests per minute per API key. When you exceed it, the MCP transport also returns HTTP 429 and Retry-After. Wait for the stated number of seconds before trying again.

Claude Code

Run one command. The HTTP transport and authentication header are included. Replace the API key:

Terminal

claude mcp add --transport http merite https://merite.ai/api/mcp \
  --header "Authorization: Bearer <api-key>"

By default, the configuration applies only to the current project. Add --scope user to make it available across projects. Verify it with claude mcp list. A useful first call is get_account, which confirms that the endpoint and key work.

Codex

Codex reads the Bearer token from an environment variable, so the key never appears as plain text in config.toml. Set the variable first, then add the server:

Terminal (macOS/Linux)

export MERITE_API_KEY="<api-key>"

codex mcp add merite --url https://merite.ai/api/mcp \
  --bearer-token-env-var MERITE_API_KEY

PowerShell (Windows)

$env:MERITE_API_KEY = "<api-key>"

codex mcp add merite --url https://merite.ai/api/mcp --bearer-token-env-var MERITE_API_KEY

This writes the following section to ~/.codex/config.toml. You can also add it manually:

~/.codex/config.toml

[mcp_servers.merite]
url = "https://merite.ai/api/mcp"
bearer_token_env_var = "MERITE_API_KEY"

MERITE_API_KEY must be set in the environment where Codex runs. Otherwise the server cannot authenticate. Verify the setup with codex mcp list.

Cursor

Add this to ~/.cursor/mcp.json globally or .cursor/mcp.json in the project. Cursor recognizes the HTTP transport from url and sends the authentication header:

~/.cursor/mcp.json

{
  "mcpServers": {
    "merite": {
      "url": "https://merite.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}

After saving, enable merite in Cursor's MCP settings.

claude.ai web connectors

Web connectors on claude.ai require OAuth. Merite currently authenticates with static Bearer API keys only, so claude.ai web connectors are not supported yet. OAuth is planned. Until then, use Claude Code from the CLI or desktop app, or use the skill path below without MCP.

Without MCP: use the skill

If your client does not support MCP, give your AI assistant the Merite skill instead. It is a compact instruction file for using the REST API directly, including intake clarifications, the two-step workflow, polling, and the feedback requirement.

Terminal

curl -O https://merite.ai/skill.md

Direct link: /skill.md. Your agent then needs only the API key and the REST reference.

Usage guidelines

Poll responsibly

After start_sourcing, delivery is usually completed within the same business day. Check get_status every 15–30 minutes, not every second. Tight polling loops do not make the shortlist arrive sooner.

Feedback is part of the workflow

After get_candidates, call send_feedback. Show the list to a human, ask what fits, what does not, and how the process worked, then return the answer as faithfully as possible. Use level candidate, job, or process. This calibrates future runs for the customer.

Confirm before the paid step

start_sourcing consumes one role package. An agent must always confirm this with its human first and must never invent intake values. Details such as remote_policy_raw and the salary ceiling matter.

Field reference and response shapes

Detailed intake contract, candidate response, and error codes.

API reference →