Connect Claude Code or Codex to Your Reference Library

refern 1.10 includes a Model Context Protocol (MCP) server. MCP is the standard that assistant apps use to call tools in other programs. With it, Claude Code, Codex, or Claude Desktop on your computer can search your reference library, tag images, and organize folders in the workspace that is open in refern. The setup takes four steps: turn on access, create a token, add refern to your app, and check the connection.

Before you start

You need refern 1.10 or later, running with a workspace open. refern can stay in the tray. The assistant app must run on the same computer: the server listens only on your computer, so a chat app in a web browser cannot reach it.

Read the privacy note in Settings > Local API. A connected app can read file names, tags, notes, and images in the open workspace. Assistant apps that run in the cloud send what they read to their provider.

Step 1: Turn on the Local API

1. Open refern and go to Settings > Local API.
2. Switch on Allow apps on this computer to access the open workspace.
3. Note the Address. It is normally http://127.0.0.1:7733.

Access stays off until you switch it on.

Step 2: Create a token with the right access

Under Create token, type a name such as "Claude Code" and choose an access level. Each level includes everything the level before it allows:

Start with Read. It lets you test searches with no risk to your library. Create a Write token when you want the app to tag, and keep Organize for a specific cleanup task. Turn on Exclude NSFW items if the app must not see those items.

Select Create token and copy the token at once. refern shows it only once. Use a different token for each app, so the change list shows which app did what.

Step 3: Add refern to your app

After you create a token, refern shows Set up an app with this token. Choose your app. The values come with your token filled in. If Settings shows a port other than 7733, use that port in the examples below.

Claude Code. Run this command, with your token in place of rfn_...:

claude mcp add --transport http refern http://127.0.0.1:7733/mcp --header "Authorization: Bearer rfn_..."

You can also choose Ask an agent and paste the message into Claude Code. It reads refern's setup guide and adds the server itself. This works for agents that can run commands on your computer, such as Claude Code and Codex. Chat-only apps cannot do this.

Codex. In Codex, add a custom MCP server named refern. Choose Streamable HTTP, not STDIO. Set the URL to http://127.0.0.1:7733/mcp and add an Authorization header with the value Bearer rfn_.... Or add this to ~/.codex/config.toml:

[mcp_servers.refern]
url = "http://127.0.0.1:7733/mcp"
http_headers = { Authorization = "Bearer rfn_..." }

To keep the token out of the file, use bearer_token_env_var = "REFERN_API_TOKEN" instead of http_headers, and set that variable where Codex starts.

Claude Desktop. Under Connect, select Save Claude Desktop bundle, then open the saved file. Claude Desktop asks for your token during setup. To edit the configuration yourself, open Or edit the config file and copy the values into claude_desktop_config.json:

{
  "mcpServers": {
    "refern": {
      "command": "<path to refern executable>",
      "args": ["--mcp-stdio"],
      "env": { "REFERN_API_TOKEN": "rfn_..." }
    }
  }
}

The refern --mcp-stdio command in this file does not open a window. It passes messages to the running app and finds the port by itself.

Step 4: Check the connection

Restart or reload your app. Then ask it a question that only works when it is connected:

Which refern workspace is open, and what access does your token have?

The app should name your workspace and its access level. It sees only the tools that its token allows, so a Read token shows no editing tools.

If the app cannot connect, check these items:

• refern is running and a workspace is open.
• Access is on in Settings > Local API.
• The address in your app matches the address in Settings.
• The token is copied in full and is not revoked.
• Your trial is active, or your license is.

What to ask your assistant

Ask in plain language. The app turns your request into tool calls. Start with one short request for each access level:

A dry run shows the changes without saving them. Moves and renames change files on disk, so back up your reference library before a large Organize task.

What to do next

Each task has its own guide, with the full workflow and more example requests:

• Find reference images with Claude Code or Codex
• Tag reference images with Claude Code or Codex
• Organize reference files with Claude Code or Codex

Review changes and undo them

Every change made through the Local API appears in Settings > Local API > Recent API changes. Each line shows what changed, how many items, which token made it, and when. Select Undo on a line to reverse it. If an item has changed again since, refern skips that item.

You can undo changes to item details and tags, appearance, creators, tag edits, tag structure names and colors, creator edits, and moves to Trash. refern keeps undo data for the newest 100 changes.

Some changes are listed but cannot be undone there: renames, moves, and copies on disk, imports, new folders, groups and links, Auto Tagger runs and reviews, smart folders, tag deletion, custom tag colors, and tag structure members. For these, ask for a dry run where one is available, or test on a small selection first.

To stop an app, select Revoke on its token. To stop all access, switch off the Local API.

What it cannot do

• Delete files. No access level can delete files from disk, empty the Trash, or delete items permanently. Trash in refern keeps the files on disk, and you can restore them.
• Work from another computer. The server listens only on your computer (127.0.0.1, ports 7733 to 7743). It refuses requests from web pages.
• Reach cloud-hosted assistants. An assistant that runs only on a provider's servers, such as a chat in a web browser, cannot connect. Use a desktop or command-line app on the same computer.
• Work without refern. refern must be running with a workspace open. The app sees only the open workspace.
• Work after the trial without a license. The free trial lasts 30 days. After that, requests are refused until a license is active. A license costs $35 once, for one user on up to three devices, on Windows, macOS, and Linux. Your files stay on disk either way.
• Add features to refern. The Local API is not a plugin system. It gives apps access to what refern already does.