Open appvitae.ai

MCP Server

Vitae.ai runs a hosted Model Context Protocol  (MCP) server so you can use Vitae directly from an AI client such as Claude Code, Codex, or ChatGPT. Once connected, the client can search candidates, manage jobs and clients, drive the ATS pipeline, run sourcing searches, trigger workflows, and talk to the AI Assistant on your behalf, using your own Vitae permissions.

Endpoint: https://mcp.vitae.ai/mcp

Transport: Stateless Streamable HTTP using the stable TypeScript SDK v2. The same /mcp endpoint supports protocol 2026-07-28 and existing 2025-11-25, 2025-06-18, and 2025-03-26 clients. SDK v1 clients can keep their existing initialize flow; modern clients use server/discover and the per-request protocol envelope and routing headers. No session ID is required. Authenticated discovery changes use legacy GET notifications or modern subscriptions/listen, with periodic access revalidation.

OAuth uses authorization code with S256 PKCE and explicit organization/module consent. Every business request revalidates the credential and current access; a catalog selection never grants permission. Opaque OAuth and personal access tokens keep their existing expiry and revocation behavior; this migration adds no refresh-token flow.

Authorization-server discovery advertises Client ID Metadata Documents alongside dynamic registration and RFC 9207 issuer responses. Success, denial, and trusted OAuth error redirects carry iss; clients should compare it exactly with the discovered issuer. Untrusted redirect targets never receive a redirect.

Metadata document client IDs must be public HTTPS URLs with a path, without credentials, fragments or dot segments. Retrieval uses DNS-pinned SSRF checks, no redirects, a five-second total deadline, and a 16 KiB body limit. Documents must identify the exact client ID and declare usable redirect URIs and public-client capabilities. A private, bounded process cache holds validated documents for at most five minutes, honors max-age, Age, no-cache and no-store, and never caches failures. Existing database client rows are metadata snapshots, not a substitute for revalidation after cache expiry.

Browser clients may send Mcp-Protocol-Version, Mcp-Method and Mcp-Name alongside authorization and content headers. Discovery and OAuth permission checks apply equally to both protocol eras.

Visit https://mcp.vitae.ai in a browser for the setup page. It asks which app you use (ChatGPT, Claude, or Grok) and opens that app with a setup message already typed, so the app walks you through the connection. Manual steps, the tool selection, Claude Code, Codex, the Grok terminal, Cursor, and the personal-access-token fallback sit in its two closed sections. Add #claude or #grok to the address to pick an app, or #claude-code or #codex to open those instructions.

Connect Claude

Claude connects the same endpoint as a custom connector, on Free and paid plans. Use the full address, https://mcp.vitae.ai/mcp. The bare address https://mcp.vitae.ai is only the setup page and cannot be used as the server URL.

  1. In Claude, open Customize, then Connectors.
  2. Choose Add, then Add custom connector. Name it Vitae, paste https://mcp.vitae.ai/mcp, and choose Add. If Claude asks how to sign in, choose Sign in now.
  3. Choose Connect next to Vitae, sign in to Vitae, and select Approve.
  4. In a new chat, ask List my open jobs.

On Team or Enterprise, an owner adds Vitae first in Organization settings, then Connectors. Members then choose Connect next to Vitae.

Connect Claude Code

Claude Code connects remote HTTP MCP servers from the terminal, then completes OAuth inside Claude Code:

  1. Run claude mcp add --transport http vitae --scope user https://mcp.vitae.ai/mcp.
  2. Start Claude Code and run /mcp.
  3. Choose vitae, then complete the Vitae OAuth flow in your browser.
  4. Verify with claude mcp list or reopen /mcp.

Connect Codex

Codex connects remote HTTP MCP servers from its CLI and authenticates with OAuth:

  1. Run codex mcp add vitae --url https://mcp.vitae.ai/mcp.
  2. Run codex mcp login vitae, then complete the Vitae OAuth flow in your browser.
  3. Verify with codex mcp get vitae or codex mcp list.
  4. Open a new Codex task if the current one does not refresh its available tools.

Connect ChatGPT

ChatGPT connects the same endpoint as a custom app. Apps with write actions need ChatGPT Business, Enterprise, or Edu on the web; on Business only workspace admins can add one, and Pro can connect with read access only:

  1. Open ChatGPT Plugins , select the plus button, then choose Add custom MCP server.
  2. Name it Vitae. Under Connection, enter https://mcp.vitae.ai/mcp as the Server URL and choose OAuth authentication.
  3. Review the warning, select I understand and want to continue, then choose Create as a plugin. Complete the Vitae sign-in and approval when prompted, then review the discovered tools.
  4. Install the resulting plugin, open a new chat, type @Vitae, and ask List my open jobs.

The current Plugins flow does not require turning on Developer Mode. Account and workspace permissions still apply. Business admins and owners manage team availability; Enterprise/Edu can also authorize creators through workspace roles. See OpenAI’s connection instructions .

Behind the scenes the client runs standard MCP discovery: it reads the protected resource metadata at https://mcp.vitae.ai/.well-known/oauth-protected-resource, follows it to the Vitae authorization server, registers itself, and runs an OAuth 2.1 authorization code flow with PKCE. Consent selects one organization and explicit vitae:<module>:<permission> scopes. vitae:default is expanded on the consent screen; the token stores only the selected explicit grant. Existing broad or organization-unbound connections must reconnect. See MCP Modules and Scopes.

app.vitae.ai and www.vitae.ai also publish this metadata, alongside api.vitae.ai itself (the authorization server), at /.well-known/oauth-protected-resource. All three point back to https://api.vitae.ai as the authorization server, so a generic MCP client that discovers Vitae through the app or marketing site (rather than mcp.vitae.ai directly) can still find and complete the same OAuth flow automatically.

Connect with a personal access token

For clients without OAuth support, generate a personal access token and paste it as the bearer credential:

  1. Open AI App Access in your Vitae settings at https://app.vitae.ai/settings/personal/mcp-access-tokens.
  2. Click New key, choose an organization and its available module permissions, and copy the token once. It starts with vmcp_ and is shown only at creation time.
  3. In your client, set the MCP endpoint and send the token in the Authorization header.
Authorization: Bearer vmcp_<prefix>_<secret>

Tokens are stored as a hash only: Vitae never keeps the plaintext, so a lost token must be revoked and replaced rather than recovered. Revoke a token from the same settings page at any time; revocation takes effect immediately.

Public tool catalog

Each operation has a specific name, direct parameters, annotations and a validated output schema. The default connection lists up to 30 recruiting essentials. ?toolsets=ats, ?toolsets=crm,outreach and other category selections list those modules plus Core. ?profile=bd selects business development; ?profile=full includes all 416 current canonical operations plus help, subject to live eligibility. Module/full selections may exceed 30. A selection never grants module access or scopes.

Use help with topic for connection, tool, access, permission or approval guidance. Use query to search entitled operations and name or action to inspect one exact schema. Help never executes another operation or grants access. The authenticated vitae://mcp/tools resource matches the selected operations accepted by this connection. Anonymous discovery exposes onboarding help only.

Fetch a Job returned by a list or search using direct arguments:

{"name":"get_job","arguments":{"jobId":"<returned-job-id>"}}

Unlisted operations, old grouped dispatch tools and undeclared input fields are refused before API access. Select a module or full profile to use an operation outside the default set. Reconnect clients after release to refresh cached names and schemas. Each response retains structured result data, human-readable content, record links and approval review metadata where applicable. The API’s /v1/agent/tools catalog publishes the same independently named inventory.

ask_vitae keeps agent delegation within independently exposed operations from the selected profile and current grant. It stores messages and uses metered AI credits. Unlisted operations and unexposed web tools are unavailable to the delegated model; profile selection never expands authorization. Original selection ceilings survive approvals and deferred work.

Clients supporting server notifications can open an authenticated GET /mcp stream with Accept: text/event-stream. The server notifies tools, prompts and resources on connection and when its 30-second access check observes a change. Streams cycle after four minutes and end when credentials become invalid; reconnect to refresh discovery. Each business request still checks current access independently. Clients without a notification stream should list tools again after reconnecting or changing permissions.

Refresh a cached tool list

Refreshing the tool catalog and running a job list again are separate operations. If your client still offers grouped names such as get_jobs, its saved catalog predates the independently named operations. The current server advertises list_jobs and get_job with direct inputs; it refuses the retired grouped wrappers. A successful help call can describe the current operations, but does not replace your client’s saved tool definitions.

For a directly connected ChatGPT plugin, open Settings → Plugins → your Vitae app → Refresh tools. Then open View details, select the app under Apps, and check that its read tools include list_jobs and get_job. Open a new chat and select the app again; a running chat can retain the earlier definitions.

For a workspace-managed custom ChatGPT app, an app owner or workspace administrator can refresh its actions from Workspace Settings → Apps with a valid connection. Enterprise/Edu administrators open the app’s ellipsis menu, choose Action Control, then Refresh. Review the updated definitions and enable the read actions you need; new actions are disabled by default. Open a new chat and select the app again. See OpenAI’s current refresh instructions .

For a direct Codex MCP connection, reconnect the configured server and open a new task if the current task retains the old tools. An installed connector’s tools may come from the connected app’s saved catalog; refresh that app’s actions first. Do not remove or broaden the Vitae permission grant to fix a catalog cache. Verify that discovery offers list_jobs and that list_jobs({status: "ACTIVE"}) succeeds before considering the catalog refreshed. Starting another chat alone is not proof of a refreshed saved app catalog.

Native jobs previews

Use list_jobs with status: "ACTIVE" for open jobs. Supported status values are DRAFT, ACTIVE, PAUSED, and CLOSED; other values fail input validation before reaching the API. get_job excludes applications and matches unless explicitly requested.

MCP Apps hosts can render the registered ui://vitae/records-v2.html resource from the tool’s _meta.ui.resourceUri. Job results include recordCardsV1 with returned job identities, titles, supported statuses, and canonical links to their Vitae boards. Empty job lists return an empty gallery. Calling the list again returns a new gallery result; loading clears previous cards and failed requests do not present previous records as current. The gallery reflects that completed request, rather than a live subscription to jobs.

Only the current preview URIs are served. Retired or unknown ui://vitae/ resources fail with a clear refresh error; there are no legacy URI aliases. Refresh the saved app tools and start a new chat, or reconnect a direct MCP server and start a new task. The current record and approval views also stop waiting after a bounded initialization or result deadline and show the same guidance. A result that arrives later can still replace that error.

Clients without MCP Apps support still receive full screened text, structured data, and record links. A working tool call with no rendered gallery means host UI support or saved UI metadata still needs verification. Catalog refresh does not establish UI support. Verify real-client rendering after deploying the fix; simulated gallery and SDK checks alone do not prove hosted acceptance.

Action approvals and retries

Read tools return data immediately. Each operation specifies whether it runs immediately or creates a pending approval. Inspect the named operation with help before requesting a change.

For example, create_job_draft saves a draft immediately, while update_job waits for approval. Reviewed drafts, notes, tags, own tasks, settings and some pause/suppression actions are immediate. Repeating an immediate write can repeat its effect, so inspect the result before retrying.

search_candidates_semantic and lookup_linkedin_profile are independently exposed operations. Semantic search quotes 1 AI credit, and LinkedIn lookup shows one lookup from your connected account’s safety budget, with the existing hourly cap. Neither calls the provider before browser-session approval.

A pending approval confirms that its proposed business action has not run. Review it in the AI Assistant or the agent inbox, then approve or decline it. Sends, charges, contracts and invoices require a person to resolve them in Vitae; an AI client cannot approve these through resolve_approval. The response identifies the required resolver. Other eligible approvals can be resolved through resolve_approval when their underlying operation is independently exposed in this selection, under the original permission rules.

Approval execution rechecks tenant and record permissions. A decline does not reach the business endpoint. For operations with requestId, reuse the same value and unchanged input across retries; conflicting reuse is refused and approved replays return the existing result.

Authentication model

OAuth and personal-token connections both produce an opaque vmcp_ token bound to the initiating member, one organization, and explicit selected scopes. The MCP server forwards your token to the Vitae API on each tool call, so every action intersects the saved grant with your current membership, role, module entitlement and record access. Queued work and approval replay recheck that original grant and keep its reviewed recipients, settings and effect ceiling. Revocation stops deferred work; changing organizations requires a new connection. The same write-approval boundary applies to both connection methods. See Authentication for the broader token model and The Vitae API for personal API keys, a separate credential type that follows the same model: the credential resolves to your user and acts with your permissions.

Security

  • Always use the HTTPS endpoint.
  • Treat a personal access token like a password. Do not commit it or paste it into shared logs.
  • Revoke tokens you no longer use, and revoke immediately if a token may have leaked.
  • OAuth connected clients can be disconnected from the client side; revoke the underlying token in Vitae settings if you want to be certain access is cut.

Troubleshooting

  • Client cannot discover the server: confirm the URL is exactly https://mcp.vitae.ai/mcp and that your client supports the Streamable HTTP transport.
  • Unauthorized errors: confirm the token is sent in the Authorization header as Bearer <token>, that it has not been revoked, and that your Vitae user has access to the feature you are calling.
  • OAuth consent loop: clear the connector in your client and re-add it so it re-runs discovery from a clean state.