Skip to content

Connect your agent

Use your workspace from Claude, ChatGPT, Claude Code, Cursor and other agents over MCP

Soloclef Notes runs an MCP server at /mcp on this site (https://your-server/mcp). Claude (on the web, desktop or phone) and ChatGPT connect by signing in with your single sign-on account; a coding agent such as Claude Code, Codex or Cursor, or an MCP client such as Open WebUI, connects with an API key. Either way the agent can then search your workspace's documents, add to them, and run the research scrapers and academic searches.

Before you start

Turn on API access for the workspace. In Workspace settings → General, switch on API key access. Only the workspace's Owner can do this. Until it is on, no agent sees the workspace, whether it signed in or uses a key.

Claude and ChatGPT: sign in

Connecting lets you use your Soloclef Notes workspace from inside Claude or ChatGPT.

Open your avatar menu and choose Connect your agent. The top of the dialog shows this server's address, a Client ID and a Client secret, with copy buttons, and the steps for each:

  • Claude: Customize → Connectors → Add custom connector (on a Team or Enterprise plan an Owner adds it under Organization settings → Connectors). Enter the server address, choose Use your own OAuth client (or open Advanced settings) and paste the client ID and secret. Then Connect and sign in. It works in Claude Desktop and the mobile app too.
  • ChatGPT: turn on Developer mode under Settings → Apps & Connectors → Advanced settings, then create an app with the server address and OAuth, and paste the client ID and secret under Advanced OAuth settings (token method client_secret_post). Then sign in when asked.

You sign in on the single sign-on page and approve access. The approval page appears every time you connect: approve only a connection you started yourself, never one from a link someone sent you. The agent then acts as your own Soloclef Notes account, found by your email: it has your role in each workspace and nothing more. It stays connected through automatic refreshes; to disconnect, remove the connector in Claude or ChatGPT. Signing in only works for people who already have a Soloclef Notes account and may use Soloclef Notes at single sign-on. Single sign-on stops anyone else on its own page, and someone it lets in who has no account is told no account matches. Everyone who may use Soloclef Notes at single sign-on can connect: no extra group or invitation is needed. The agent can't create an account. If you don't have one yet, ask the administrator for one through the contact page (your server's contact page).

Coding agents: API key

Create an API key. In User settings → API Access, choose Create API key, give it a name and, if you like, an expiry. Copy the key when it is shown: it is shown only once. Every account can make its own; a key acts as you and nobody else.

Then open your avatar menu and choose Connect your agent.

  1. Keep Remote selected: it uses this server, with nothing to install.
  2. Pick your agent's tab: Claude Code, Codex, OpenCode, Cursor, Claude Desktop, VS Code, Windsurf or Gemini CLI.
  3. Follow its steps and paste the configuration, replacing ss_pat_your_key_here with your key. The key travels as a Authorization: Bearer header. An agent that can't set that header can send the key as an X-API-Key header instead.

In Claude Code, for example, run the command shown, then /mcp inside Claude Code should list soloclef as connected.

Open WebUI (and other MCP clients). Add a tool server of type MCP with the address (https://your-server/mcp), authentication bearer, and the key. Open WebUI can be limited to some of the tools with its function-name filter — to give it only the academic searches, list soloclef_pubmed_search,soloclef_arxiv_search,soloclef_preprint_search,soloclef_scholar_search. Grant it to the accounts that should use it.

What the agent can do

The tools are all named soloclef_…:

  • Workspaces: soloclef_list_workspaces, soloclef_select_workspace. If the key can see only one workspace, it is used without asking. Otherwise the agent picks one with soloclef_select_workspace, or names it in each call. With an API key, the choice is remembered for that key, so agents that share a key share it. With a sign-in, it is remembered for your account, so all your connected Claude and ChatGPT agents share one choice. Either way it lasts until the server restarts.
  • Search and read documents: soloclef_search_knowledge_base, soloclef_list_documents, soloclef_get_document.
  • Change documents: soloclef_add_document (a note in text or Markdown), soloclef_upload_file, soloclef_update_document, soloclef_delete_document. New documents are indexed in the background. soloclef_upload_file reads a file path on the machine where the MCP server runs. With Remote that is this server, so a file on your own computer can't be uploaded: send its text with soloclef_add_document instead, or use Self-host. Uploads use the Local parser, skip duplicates, and can be up to 500 MB. soloclef_update_document replaces a document's whole text and keeps its title; Studio outputs can't be changed. Deleting is permanent.
  • Research scrapers: Google Search, web crawling, Reddit, YouTube, Instagram, TikTok, Google Maps, Indeed, Amazon and Walmart (for example soloclef_google_search, soloclef_web_crawl), plus soloclef_list_scraper_runs and soloclef_get_scraper_run for past runs.
  • Academic search: soloclef_pubmed_search (optionally limited to publication years, or with open-access full-text excerpts), soloclef_arxiv_search, soloclef_preprint_search (medRxiv or bioRxiv; preprints are not peer reviewed) and soloclef_scholar_search (Google Scholar, snippets only). Each returns up to 30 results (10 by default) for a query of up to 500 characters. They cost no credits and add nothing to the workspace.

The agent works on workspace documents, not on notebooks: it can't ask a notebook's chat or make Studio outputs. Documents it adds can be picked into a notebook with Add sources. It can't read your email either: there are no mail tools, and mail is never stored as documents.

What the agent may do follows your role in the workspace. With a Viewer's role it can search and read documents and run scrapers and academic searches; an Editor can also add, upload and update documents; only the Owner can delete them.

Limits

  • A workspace allows 120 scraper and academic requests a minute, shared with research in its notebooks. Above that the agent is told it is rate limited.
  • Each call waits up to 180 seconds.
  • Results shown to the agent are cut to 20,000 characters, with each scraper text field cut to 1,500 and each search passage to 500. A scraper run's full output stays in the stored run.
  • soloclef_search_knowledge_base returns up to 20 results (5 by default).

When a call is refused, the agent passes on why: for example that the workspace is out of credits, that API access is off, or that it is rate limited.

Scraper runs made with your key are listed under User settings → API Access → API runs, with their cost. To cut an agent off, delete its key, or for Claude and ChatGPT remove the connector there.

API runs shows every scraper run and notebook research search in the current workspace, by anyone; Origin says API key for calls made with a key or by a signed-in agent. Academic searches are not listed. To cut off every agent at once, the workspace Owner can turn off API key access.

Limits for signed-in agents

  • A sign-in lasts an hour and the agent refreshes it on its own, for up to 30 days without signing in again.
  • If your access to Soloclef Notes at single sign-on is taken away, the agent stops working within an hour; if your Soloclef Notes account is deactivated, at once.
  • The server remembers that a sign-in is valid for up to a minute, then asks again.
  • Agents that can't paste a client ID and secret (Claude Code and other coding agents) use an API key instead.