MCP server

Connect it#

Create a key in the API page, then point your client at this address with the key in an Authorization header. Most clients want the JSON below; the one you use has its own page with the exact file and the exact spelling.

{
  "mcpServers": {
    "refolk": {
      "url": "https://www.refolk.ai/api/mcp",
      "headers": { "Authorization": "Bearer rfk_live_your_key_here" }
    }
  }
}

Streamable HTTP, stateless, protocol revision 2025-06-18, with two older revisions still accepted so a client on last year’s build still connects.

Your client, step by step#

• Claude Code→One command. Search for people from the terminal you are already in.
• Cursor→Add it once to mcp.json and every chat in the editor can search.
• Claude Desktop→Search for people inside a normal Claude conversation.
• VS Code→Copilot's agent mode gets four tools and a real people index.
• Windsurf→Cascade can find the people, not just the code.
• Cline→Add a remote server from the MCP pane and keep working.

The four tools#

What the assistant gets, and what each one spends. The descriptions the model reads say the same thing, so it can tell you what a search will cost before it runs one.

• refolk_search_people - Search for people in plain English. Find real people by describing them in a sentence. Plans the search, reads public sources live, cross-references them, and returns a ranked shortlist with the evidence behind each pick. (~10 reserved, reconciled down)
• refolk_filter_people - Search for people with exact filters. Find people by an exact filter set: titles, skills, seniority, employer size, location, years of experience. No model runs and nothing is ranked, so the same filters return the same page every time. (1 credit)
• refolk_plan_filters - Turn a description into a filter set. Convert a plain English description into the filter set refolk_filter_people takes, without running a search. (1 credit)
• refolk_credit_balance - Check the credit balance. How many credits are left on this account, and what each kind of search costs. Free to call. Worth checking before a long run of searches. (free)

What to ask it#

The point of having this in a conversation rather than in a script is that the next question is free. Ask for a shortlist, then narrow it, then ask what the people on it have in common.

• “Find me staff backend engineers in NYC who shipped Rust in production, then tell me which of them have changed jobs in the last year.”
• “Who maintains the Rust web frameworks that are growing fastest? Draft a first message to the top three.”
• “Build me a filter set for senior platform engineers at mid-size fintechs in Berlin, show it to me before you run it.”

The last one is the pattern worth learning: plan the filters first, look at them, then spend the credit on results.

What it can and cannot do#

• It reads, it does not write. There is no tool here that sends a message, changes your account, or touches anything but a search.
• It spends credits. Two of the four tools cost something, and both say so in the description the model reads. Your client will ask before the first call.
• The key stays in your config. The client attaches it to the request; the model never sees the header.
• Revoking is immediate. Revoke the key in the API page and the next call from that client fails, without signing you out or touching your other keys.

When it will not connect#

• The server is listed but has no tools. The key is missing or wrong. Every request is authenticated, so a bad key looks like a server with nothing in it. Check it with curl https://www.refolk.ai/api/v1/me -H "Authorization: Bearer ...".
• Nothing happens at all. Some clients only know how to launch a local process. Those need the mcp-remote bridge rather than a URL - the Claude Desktop page shows the shape.
• The config is ignored. The top-level key differs between clients: most want mcpServers, VS Code wants servers, Windsurf wants serverUrl rather than url. Use your client’s page rather than a generic snippet.
• A search times out. A search in plain English takes thirty to ninety seconds. Some clients cut tool calls off sooner than that; the filtered search returns in a second or two and is the better tool inside a conversation that is in a hurry.