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 Ask Vitae agent on your behalf, using your own Vitae permissions.

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

Transport: Streamable HTTP.

Visit https://mcp.vitae.ai in a browser for a short connect page with client-specific Claude Code, Codex, and ChatGPT tabs, a copyable agent setup prompt, and the personal-access-token fallback.

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 connector:

  1. Open ChatGPT settings, go to Apps & Connectors, open Advanced settings, and enable developer mode if your workspace allows it.
  2. Go to Settings > Connectors > Create.
  3. Use Vitae as the connector name and paste https://mcp.vitae.ai/mcp as the connector URL.
  4. After ChatGPT lists the tools, open a new chat, click the plus button, choose More, and add the Vitae connector to the conversation.

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. The token it receives is a long lived Vitae credential scoped to vitae:mcp.

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 MCP access tokens in your Vitae settings at https://app.vitae.ai/settings/personal/mcp-access-tokens.
  2. Generate a token and copy it 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.

What the agent can do

The server exposes Vitae as a set of MCP tools. Each call runs with your account’s permissions and organization scope. Capabilities include:

  • Ask Vitae agent: start and list conversation threads, ask the agent questions, pin and archive threads.
  • Candidates: search, create, update, and delete candidates; manage candidate pools; read resumes and best matches.
  • Jobs: draft, list, update, and archive jobs.
  • Clients: create, list, update, and churn clients; view the client portfolio.
  • ATS pipeline: read the pipeline board, move applicants individually or in bulk, and summarize pipeline state.
  • Sourcing and search: start sourcing searches, review search history and results, and inspect search details.
  • Signals: list scored Signals (list_signals; list_signal_opportunities is deprecated), run a scan, and update signal status.
  • Workflows: draft, list, run, and trigger workflows, and resolve approvals.
  • Reporting: read dashboards, list adaptive surface blocks, and export reports.

Approvals for write tools

Read-only tools return data immediately. Tools that change recruiting records create a pending approval instead of making the change immediately. This applies to:

  • Creating, updating, or archiving jobs.
  • Creating, updating, churning, or deleting client and candidate records.
  • Moving one applicant or a group of applicants to another pipeline stage.
  • Creating, updating, or deleting candidate pools.
  • Running or triggering workflows, creating workflow drafts, and saving dashboard configuration.

The tool response includes the pending approval and confirms that nothing has changed yet. The same approval appears in Ask Vitae and the agent inbox. Review the proposed fields there, then approve or decline it. An approved action runs through the same tenant checks and audit trail as an action proposed by the in-app agent; a declined action never reaches the underlying business endpoint.

Some non-record actions remain immediate by design: read tools, reversible thread preferences, bounded sourcing searches, Ask Vitae chat, and recruiter-authored interview response capture. resolve_approval is also immediate because it is the explicit user decision that completes or declines an existing audited approval.

Authentication model

OAuth and personal-token connections both produce an opaque vmcp_ token scoped to vitae:mcp. The MCP server forwards your token to the Vitae API on each tool call, so every action uses your account permissions and organization scope. 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.