Agents

MCP search server

Hayfork runs a hosted MCP server, so Claude Code, Cursor, VS Code and other MCP clients can search your websites and files without any code. Add one URL and a search key to the client, and its agent can find documents and answer from them with citations.

Connection details

Setting	Value
URL	`https://api.hayfork.dev/mcp`
Transport	Streamable HTTP. Stateless, one JSON reply per call.
Authentication	`Authorization: Bearer <key>` on every request. A search-scoped key is all it needs.
Tools	`search` and `retrieve`, both read-only.

Set it up

First create a key: in the console settings, choose Create key and give it only the search scope. A search key can read the workspace and change nothing, which is all an agent needs.

Claude Code

claude mcp add --transport http hayfork https://api.hayfork.dev/mcp \
  --header "Authorization: Bearer $HAYFORK_KEY"

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project to share it with your team:

{
  "mcpServers": {
    "hayfork": {
      "url": "https://api.hayfork.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_SEARCH_KEY" }
    }
  }
}

VS Code

Add the server to .vscode/mcp.json in your workspace:

{
  "servers": {
    "hayfork": {
      "type": "http",
      "url": "https://api.hayfork.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_SEARCH_KEY" }
    }
  }
}

Other clients

Any client that can connect to a remote MCP server over HTTP and send a custom header works the same way: the URL above and the Authorization header. Clients that only support OAuth sign-in, such as the ChatGPT connector directory, are not supported yet.

Tools

Both tools take a collection by its id or by the name shown in the console. Names match without regard to case. Numbers outside the allowed range are moved to the nearest limit rather than refused.

search

Ranked documents for a question, one hit per document, with a snippet, the source URL or file name and the heading the match sits under. Use it to find which documents are relevant.

Argument	Type	Default	Notes
`collection`	string	required	Collection id or name.
`query`	string	required	A question or keywords.
`top_k`	integer	10	1 to 50 documents.

Returns query, total and results, each with document_id, title, snippet, source, heading_path and score.

retrieve

The passages that best answer a question, numbered [1], [2] and so on, with the title and source of each, sized to an optional token budget. Use it when the agent needs text to answer from and cite.

Argument	Type	Default	Notes
`collection`	string	required	Collection id or name.
`query`	string	required	The question to answer.
`top_k`	integer	8	1 to 50 matched passages.
`max_tokens`	integer	none	100 to 64,000. Passages are trimmed to fit.
`context_window`	integer	0	0 to 2 neighbouring passages added around each match.

Returns query, token_estimate, text with the numbered passages ready for a prompt, and citations, each with citation, document_id, title, source and heading_path. The same options are explained in more depth for the retrieve endpoint.

Give each agent its own collection

An agent searches better over a few close sources than over everything you have. A support agent that only needs the help centre should be pointed at a collection that holds only the help centre. Collections cost nothing extra and a source can sit in several, so make one per agent or per task. If two collections share a name, pass the id.

Usage and limits

Each tool call counts as one search against your plan, the same as a REST call. When a limit is reached the tool returns the same message the API would.
The server keeps no session, so one key can be used from many clients and machines at once.
A key belongs to one workspace. The tools can only see that workspace's collections.

Security

Use a search key. It cannot add, change or delete anything. Revoke it from the console at any time and the client stops working immediately.
Returned text is content, not instructions. The server tells the model to treat indexed text as data and never to follow directions found inside it. If you index pages you do not control, keep that rule in your own agent's prompt too.
Keep the key out of shared files. When a project's mcp.json is committed, read the key from an environment variable if your client supports it, or keep the file out of version control.

Troubleshooting

Message	What to do
`Bearer API key required`	The client is not sending the header. Check the `headers` entry and restart the client after editing its config.
`Invalid API key` or a `401`	The key was revoked, has expired or was copied incompletely. Create a new one in the console.
`No collection named '…' in this workspace`	Check the name in the console's Collections page, or pass the collection id.
`Several collections are named '…'`	Pass the collection id instead of the name.

To check that the server is reachable from your machine, call it without a key. A 401 with Bearer API key required means it is up and waiting for a key:

curl -i -X POST https://api.hayfork.dev/mcp