Agent keys and MCP

An agent key gives one AI app read access to the folders and files you pick, and nothing else. It works over MCP and over the HTTP API. Manage keys under Agent keys in the console.

Create a key

Choose New › Key for an agent… and fill in three things:

• Agent name. It becomes the MCP server name, so name it after what it holds, such as hr-handbook, not after the app, such as hr-bot. Names use 2 to 32 lowercase letters, digits and dashes, starting with a letter, because apps put the name in front of the tool names.
• What it’s for. Sent to the model over MCP, so it knows when to use this key. Say what the documents are about and when to use them. The HTTP API doesn’t use it.
• What it can read. Pick folders and files. Only those you manage are listed. A folder includes the folders inside it, and files added to it later.

The new key is shown once. Copy it and keep it on the server that runs your agent, never in a browser: anything that reaches a browser can be copied.

One app, several folders

To let one app search several sets of documents, put all the folders in one key rather than making a key for each:

• Every key you add to an app brings its own four tools and introduction, and many apps send all of them to the model on every call.
• With one key, a question that spans folders is one search with one ranking. With several keys the model searches each one on its own, and the results can’t be compared.

Then use the description to say what each folder holds, one line each:

HR and finance documents of Example Corp.
- Handbook: leave, benefits and conduct.
- Payroll: pay dates, tax forms and expense rules.
Use it for employees' questions about HR and pay.

The model sees the folder names, and can narrow a search to some of them or search them all.

You can only put in what you manage. If two keys were made by different people, add each one to the app on its own.

Change a key

• Edit what it can read takes effect right away. The key’s value stays the same.
• Rename and describe changes the name and description. AI apps see them the next time they connect.
• Delete removes the key. Anything using it stops working right away.

When someone stops sharing a folder or file with you, it is also removed from the keys you manage. Sharing it again does not add it back. See Sharing.

If everything a key could read is deleted, the key shows Nothing and its searches fail. Edit what it can read to fix it.

Roll a key

To replace a key’s value, choose Roll key… and pick when the old value stops working: right away, in 1 hour, in 24 hours or in 7 days. The new value is shown once and works at once.

Until the old value stops, the key is marked Rolling, and its details show when the old value was last used. Once your agent uses the new value, click End it now to stop the old one early. A key can’t be rolled again while its old value still works.

If an admin revoked a key’s value, the key shows No value. Roll it to get a new one.

Personal keys

A personal key reads everything you can read at the moment, for your own code. It works with the HTTP API but not with MCP, because there is no set of folders to tell a model about.

Choose New › Personal key — read, or Personal key — read and write, which can also upload files to folders you manage. A personal key stops working if your account is deactivated. Personal keys roll the same way as agent keys, and Revoke key ends one.

Connect over MCP

The MCP endpoint is /mcp on the same address as the console, and it takes an agent key in the Authorization header. For Claude Code:

claude mcp add --transport http hr-handbook https://sergo.example.com/mcp \
  --header "Authorization: Bearer <agent key>"

The key’s details pane, under How to use this key, shows this command and a JSON block for apps that take an mcpServers setting.

The server offers four tools:

• search(query, limit, folders) searches the documents the key can read. It returns the best-matching excerpts, at most half of them from one document, grouped by document. Each excerpt has its page, and its section in Word files, and says when the page may hold a figure, chart or table that the text misses. folders takes folder names or paths such as handbook/2024; a folder includes the folders inside it.
• list_documents(folders, limit, offset) lists the documents the key can read, newest first, with their folder, type and page count. Documents that are not indexed yet are marked.
• read_document(document_id, page, to_page) reads the text of one page, of the pages from page to to_page, or of the whole document (up to a limit) when page is left out.
• view_page(document_id, page, format) returns one page as a picture, or as a one-page PDF with format: "pdf", for pages whose text is missing or where a table or figure matters. Works for PDFs and for Office files that have a PDF copy.

The exact tool descriptions, what each tool returns and the errors are in the MCP reference.

To check what a key gets before you hand it to an app, search as that key in the console. See Search.

Use the HTTP API

The same key works with the HTTP API under /v1. The console shows a ready-to-run curl example when you create a key. Every call a key can make is in the HTTP API reference.

Response	What it means
401	The key is wrong, was revoked, or is an old value that has stopped working.
403 personal_key	MCP only takes an agent key.
404	The document doesn’t exist, or the key can’t read it.
422 empty_scope	Everything the key could read was deleted.