Developers
MCP server
Work with your jobs, candidates, notes and automations from Claude, ChatGPT, Cursor and other AI tools through the Model Context Protocol. Otter hosts the server, so there is nothing to install: add one URL and a workspace API key.
Before you start
- Server URL:
https://app.otter.diy/api/mcp(Streamable HTTP) - A workspace API key. An admin creates one in Settings → API Keys. Choose Read only if the AI tool should only look things up, or Read & write to let it update jobs, add notes and switch automations on or off.
- The workspace must be on Growth or Scale, the same as the REST API.
Treat the key like a password. Don't paste it into chats or commit it to a repository. To disconnect a tool, revoke its key in Settings → API Keys; that takes effect immediately.
Claude (claude.ai, Claude Desktop)
- Open Customize → Connectors, click +, then Add custom connector. (On Team and Enterprise plans an owner adds it under Organization settings → Connectors first.)
- Name it Otter Hire and paste the server URL:
https://app.otter.diy/api/mcp - Click Add, then Connect. An Otter page opens: paste your API key and click Connect.
Claude Code
claude mcp add --transport http otter https://app.otter.diy/api/mcp \ --header "Authorization: Bearer otter_sk_…"
ChatGPT
- In ChatGPT on the web, open Settings → Apps → Advanced settings and turn on Developer mode. (On Business and Enterprise workspaces an admin may need to allow custom connectors first.)
- Go to Settings → Apps and click Create.
- Name it Otter Hire, paste the server URL
https://app.otter.diy/api/mcp, and choose OAuth for authentication. - An Otter page opens: paste your API key and click Connect. Back in ChatGPT, finish creating the app, then turn it on in a chat from the + menu.
ChatGPT decides which plans can use custom apps and whether they may make changes; on some plans only the read tools are available.
Cursor
Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project you don't commit keys from:
{
"mcpServers": {
"otter": {
"url": "https://app.otter.diy/api/mcp",
"headers": { "Authorization": "Bearer otter_sk_…" }
}
}
}Leave out headers and Cursor opens the Otter page to paste the key instead.
Other tools
Any MCP client that supports remote servers works. Give it the server URL and either send the header Authorization: Bearer otter_sk_…, or let it sign in with OAuth, which opens the same Otter page to paste a key. For example, in OpenAI Codex:
# ~/.codex/config.toml [mcp_servers.otter] url = "https://app.otter.diy/api/mcp" bearer_token_env_var = "OTTER_API_KEY"
Tools
list_jobs: list jobs in the workspaceget_job/update_job: read a job, or change its title, location, salary, description or status (updating needs a read & write key)search_candidates: search by name, email, or free textsmart_search_candidates: describe who you want in plain words (“React developers in Pune with 5+ years”) and get matches with why each one matchedbulk_import_resumes/get_bulk_import: add up to 20 resumes from links into the database, a job or a talent pool, then check what was added, matched or failed (read & write key)list_candidate_emails: a candidate's emails with Sent / Delivered / Read statuslist_candidate_messages: a candidate's SMS and WhatsApp messages with Sent / Delivered / Read statuslist_interview_kits: a job's interview kits per stage (questions, what good looks like, scorecard), or the reusable templateslist_notes: read team-visible notes for a candidate or applicationcreate_note: add a note on a candidate or application (needs a read & write key)create_candidate: add a candidate, optionally onto a job; the same email reuses the existing person (needs a read & write key)move_application: move an application to another stage of its job (needs a read & write key)list_automations,set_automation_enabled,list_automation_runs: see which automations are on, switch one on or off (read & write key), and read its run logget_application: one application with its stage, status, answers to the job's application questions (knockout flags never reject anyone) and the cover notelist_referrals/refer_candidate: see employee referrals and their status, or refer someone to a job (read & write key)list_scheduling_links/create_scheduling_link: see self-scheduling links (open, booked, cancelled or expired), or create one for a candidate to pick a time (read & write key)list_approvals,request_approval,decide_approval: see, request and approve or decline job and offer approvals (requesting and deciding need a read & write key)draft_job_description,rewrite_job_description,check_job_description_language: the AI job writer: draft a job post from a short brief, rewrite, shorten or expand one (never saved, never invents pay), or check it for biased wording (free, no AI)
Apps that only run local servers (stdio)
Some apps, such as older Claude Desktop versions configured through a JSON file, can only start a local program. Use the open-source mcp-remote bridge, which connects that app to Otter's hosted server (needs Node.js 18 or later). There is no separate Otter package to install.
{
"mcpServers": {
"otter": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://app.otter.diy/api/mcp",
"--header", "Authorization: Bearer ${OTTER_API_KEY}"],
"env": { "OTTER_API_KEY": "otter_sk_…" }
}
}
}Check the connection
This should print the list of tools. Replace the key with yours:
curl -s https://app.otter.diy/api/mcp -H "Authorization: Bearer otter_sk_…" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Troubleshooting
- 405 Method Not Allowed, or “SSE error”: the app is using the older SSE transport. Choose Streamable HTTP (in config files usually
"type": "http"or--transport http), not SSE. Otter's server doesn't offer SSE. - 401 Unauthorized, or the app asks you to sign in: the key is missing, mistyped or revoked. The header must be exactly
Authorization: Bearer otter_sk_…(with the word Bearer and a space). Settings → API Keys shows when each key was last used, so you can tell whether the app reached Otter. - Connected but no tools: reconnect or restart the app after adding the key; most apps only fetch the tool list when they connect. Read-only keys still list every tool but can't run the ones that make changes.
- 403: the workspace's plan doesn't include API access, or the key belongs to a different workspace.
Same rules as the REST API
The MCP server runs on the REST API: each key only sees its own workspace, read-only keys can't change anything, and the same rate limit applies (600 requests a minute per key). It works on Growth and Scale. The public demo workspace can't be connected.