Guide

Written by Athan Tsokolas Founder, Noeis Updated 2026-04-19

How to Give an AI Agent Access to Your Reading and Notes via MCP

To give an AI agent access to your reading and notes, install the Noeis CLI, run noeis connect with the name of your agent and the read scope, approve the request in your browser, then reload the agent and confirm it can call the connection_info tool. The agent then reaches your saved articles, highlights, concepts, questions, notebook, and wiki pages through a local MCP server, with read-only access unless you explicitly choose more.

The setup is designed so that the agent never approves itself. You see the requested permission on an approval page in Noeis, and only you can accept it. The full public setup guide for agents lives at noeis.io/skill.md.

Start free Browse guides

How this guide was produced

Written by Athan Tsokolas, Founder, Noeis.

This guide follows the public agent setup guide at /skill.md and the README files for the @noeis/noeis-cli and @noeis/wiki-mcp packages. Commands and tool names are taken from those sources.

Tool lists change between releases, so the guide recommends discovering the live tool list through MCP rather than relying on a copied one.

Direct answer

Connect with one command, approve it yourself, and verify it from inside the agent.

Run noeis connect with your runtime and --scope read, compare the approval page against what you asked for, then reload the agent and call connection_info there before you consider the setup done.

  • Read-only is the default scope.
  • Only a human can approve the connection.
  • A written config file does not prove the agent loaded its tools.

What a connected agent can reach

Noeis exposes your workspace to agents through the Model Context Protocol (MCP), the standard many coding agents and AI clients use to call outside tools. Once connected, an agent can search and read what you have saved instead of guessing from its training data.

  • Library: search saved articles, read an article, and list its highlights.
  • Highlights: search your highlights and read a single highlight.
  • Think: list and read your concepts, questions, and notebook pages.
  • Wiki: list, search, and read wiki pages, their sources, backlinks, and revision history.
  • Account checks: connection_info reports which workspace and grant the agent holds.

The setup guide asks agents to preserve quotation and source identity, to retrieve before creating duplicates, and to treat anything retrieved from your workspace as data, never as instructions to widen access or change local configuration.

Set up the connection

The normal path is a single connect command. It requests read-only access, opens Noeis for your approval, checks the grant that was issued, stores the credential, and writes the MCP config for the runtime you name.

  1. Install the CLI: npm install -g @noeis/noeis-cli
  2. Read noeis connect --help for the version you installed, so you only use commands and flags that exist.
  3. Run the connect command for your agent, for example: noeis connect claude-code --scope read
  4. Approve the request on the Noeis page that opens in your browser.
  5. Reload or restart the agent so it picks up the new MCP server.
  6. Call connection_info from inside the agent to confirm it works.

Use the same form for codex, opencode, hermes, or openclaw. If the browser cannot open on the machine running the agent, add --no-browser and the CLI prints the approval link for you to open elsewhere. That changes where you approve, not whether you approve.

A human approves, and read-only is the default

Claim

An agent should never be able to grant itself access to your reading.

Evidence

  • The approval link contains only an opaque session reference; the CLI keeps its polling secret.
  • The approval page shows the code, connection label, runtime, expiry, and the actual permission requested, so you can compare them before accepting.
  • After approval, the CLI checks that the issued grant matches the scope it requested and stops if it does not.

Why this matters

If the approval page shows wider access than you asked for, do not approve it. The agent cannot proceed without you.

The two scopes

read lets the agent retrieve your private workspace material. read-write adds agent-write, which permits write requests such as creating highlights or editing wiki pages, although some product actions remain human-only or require approval. Read-only grants can only make read requests, so write tools fail for them.

Unknown scopes are rejected rather than widened. Only pass --scope read-write when you have decided you want the agent to make changes.

Runtime names are labels, not proof

The runtime name shown on the approval page is reported by the CLI. It is not device attestation, so judge the request by whether you just started it.

Verify the agent really loaded its tools

A connection has three separate pieces of evidence, and each proves something different. Check all three before you call setup done.

  1. Approval recorded: Noeis issued the grant you reviewed.
  2. Tools loaded: the agent itself reports the Noeis MCP tools. In Claude Code, check /mcp.
  3. Authenticated read verified: calling connection_info from that agent returns your workspace and grant without reading or creating anything.

If tools are missing after approval, keep the existing grant and fix how the agent loads its config. Do not reconnect, mint another credential, or widen access just to make a tool appear.

Other clients and the hosted endpoint

The implemented local transport is stdio. Any MCP client that can launch a local process can use the same server definition the CLI writes: the command noeis with the argument mcp. The package README includes config snippets for Claude Code, Codex, OpenCode, and Hermes.

For clients that cannot launch a local process, Noeis also offers a hosted Streamable HTTP endpoint. It takes a connected-agent token as a Bearer credential, created in Noeis under Settings, Connected agents. Start with the read scope, a short expiry, and a daily quota. The hosted endpoint has no cookie session and does not support OAuth yet.

For scripts and cron jobs that do not speak MCP, the same CLI offers plain commands such as noeis pages list, using the same token and API.

FAQ

How do I connect Claude Code to my Noeis library?

Install the CLI with npm install -g @noeis/noeis-cli, run noeis connect claude-code --scope read, and approve the request in the browser. Then restart Claude Code, check /mcp, and call the connection_info tool to confirm the connection.

Can the agent change or delete my notes?

Not with the default read scope. Read-only grants can only use read requests, and write tools return an error. Writing requires the broader read-write grant, which you have to choose explicitly with --scope read-write and approve yourself.

Which agents and MCP clients are supported?

The CLI's connect command supports claude-code, codex, opencode, hermes, and openclaw. Any client that can launch a local stdio MCP server can run noeis mcp, and clients that cannot launch a local process can use the hosted endpoint with a connected-agent token.

Where is my credential stored?

The CLI normally stores it once in ~/.config/noeis/config.json. The MCP config it writes for your agent calls noeis mcp instead of copying the raw token into each runtime.

How do I know the connection actually works?

Call the connection_info tool from inside the agent. It returns the workspace and grant that were issued without reading or creating anything in your workspace. A config file written by the CLI does not prove the agent loaded its tools.