Appendix : MCP Server

Quick links:

Basic Setup
Advanced Setup
Controlling MCP's Behavior

MCP Server

As discussed in the Getting Started > AI in Practice section, an MCP server is a controller between DEVONthink and external AI applications, giving them commands and controlled access to your databases. Here we'll cover some benefits and setup information. As Anthropic is the one who started this all and setting up MCP with their Claude application requires very little effort, we'll use it as our example.

For those curious about advantages of using the MCP server, here are some things to know:

Requires No Coding: No programming skills are needed — just the ability to compose a clear query or command.
Easy to Install: The MCP server is a core part of DEVONthink, requires no separate modules, and updates automatically with the application.
Targeted Editing: When editing text documents, the AI works on specific sections rather than rewriting the whole document, reducing the risk of unintended changes.
Local by Default, Remote Optional: The server runs on your local machine by default. Remote access is possible but requires much more configuration.
Safe and Private: The AI has no access to your database internals; all changes are controlled by DEVONthink. Sensitive data (credit cards, passwords, etc.) is stripped before it reaches the LLM, items excluded from AI & MCP access are fully ignored, and your documents never leave your Mac beyond what the LLM sees during a conversation.

And if you're wondering what kinds of things you can do with the MCP server, there are many commands, capable in isolation and powerful when run in combinations. Here are some aspects of DEVONthink you can control via the MCP :

Database & Navigation: Get information about databases, selections, group hierarchies, etc.
Record Management: Create, modify, organize, and delete items. Get and set metadata on items, e.g., tags, labels, properties, etc. Import and export documents.
Search & Discovery: Search for items, classify documents, lookup similar records or ones identified by attributes like name, path, etc.
External AI Features: Process image data with vision, transcribe audio, extract content for AI use, or use AI searches, e.g., on PubMed or arXiv.
Content Processing: OCR scans, convert between formats, merge documents, or clip web content into your databases.
Academic/Research Tools: Extract DOI/ISBN/ISSN numbers, find and download documents based on those and other attributes, get and apply bibliographic metadata to documents.

So you can command your AI application with directives like, Transcribe the interview recordings from today and save the transcript as a Markdown note, grouped by the interviewee name in a monthly group.

Basic Setup

DEVONthink's MCP server is built to be run and accessed on the same Mac, letting you leverage an external LLM and our application's powerful automation functions. Fortunately, the setup is usually very simple as illustrated in the next paragraph.

First you need to set up DEVONthink's MCP server in the AI > MCP settings. To get up and running quickly, we'll just check Redact sensitive content and Install for Claude Desktop. Logically, if you're using Claude Code, Codex, or the Hermes Agent, you would install the appropriate option. Enabling Launch at login is a good idea and lessens friction if you choose to explore other applications in the future. Now open Claude.app and ask something DEVONthink-related, like, List the documents added yesterday, but ignore RSS articles. You are now using our MCP server to interact with your documents and databases!

Other MCP Clients: You may not be running one of the support AI applications but that doesn't mean you're out of luck. Refer to the client's documentation to see if it supports standard input/output (stdio) or URL-based communication and how to set up the MCP connection. But be aware setting up access from other applications may require editing a configuration file manually.

HTTP Connections: Some AI applications use a web-based method, e.g., http(s), for the communication. DEVONthink supports this as well, even as an alternate connection method for those supporting both. For connecting on your Mac, the server listens at http://localhost:8420 by default, requiring no authentication or encryption required. It communicates using JSON-RPC 2.0 over POST requests with a Content-Type: application/json header, a commonly used method.

You also need to register the server URL with your MCP application so it knows how to connect. When used with the supported clients, do this to use the URL access method. Check the documentation for configuring other clients.

Open /Applications/Utilities/Terminal, paste the appropriate command for your application, and press Return, e.g.,:

Terminal:

# Claude Code

$ claude mcp add --scope user --transport http devonthink http://localhost:8420

# Codex

$ codex mcp add devonthink --url http://localhost:8420

# Hermes Agent

$ hermes mcp add devonthink --url http://localhost:8420

Advanced Setup

While initially built for on-device access, it's also possible to connect another device to the MCP server. When connected to the MCP server, you can make inquiries about the host's databases and even run skills based on the replies. While we can't offer application-specific instructions for every instance, here is a generic overview of the requirements.

If you want to access your DEVONthink MCP server from another Mac or device on your network, you'll need two important authentication elements: a TLS certificate and a bearer token. The server won't allow network access without both pieces in place.

Bearer Token: This is a long alphanumeric code specific to your MCP server. When a device tries to connect to the MCP server, it must present this token or it will be denied access.

TLS Certificate: The server requires a proper TLS identity stored in your macOS Keychain. Self-signed certificates won't work so you'll need one from a trusted Certificate Authority. While we can't provide explicit instructions for getting a certificate, some common places to acquire one are: from your organization's IT department, via Let's Encrypt in conjunction with tools like Certbot, or by purchasing one from providers like DigiCert, Sectigo.

Once you have your certificate, import it into Apple's Keychain Access application. Double-click the keychain entry, open the Trust section, and set it to Always Trust. Save the change when closing the window then return to DEVONthink. If set up properly, you should see it appear TLS Certificate popup discussed below.

Setting up the Server Mac: Once you have acquired and added a TLS certificate to Keychain Access, setting up the server Mac is straightforward. Open the AI > MCP settings and do these things:

Enable Launch at login. This ensures the server is up and running when DEVONthink launches.
Set the Accept Connections popup to From the local network. Note the URL field as you will use it on the connecting device.
Click the Create button to generate a new Bearer Token.
Select your certificate in the TLS Certificate popup.
Optionally, set a specific Port if you need to.

Note: Changing these settings modifies the MCP configuration file so you don't have to manually change it. However, if you know what you're doing, the file can be found at ~/Library/Application Support/DEVONthink/MCP/config.json.

Connecting from Another Mac: Once the host Mac is configured, add access to the server on the connecting Mac using your client. Armed with the URL and bearer token, this may be done in the Terminal application, e.g., for Claude Code:

Terminal:

$ claude mcp add --scope user --transport http devonthink https://your-host.local:8420 \

In the above command, replace your-host.local:8420 with the URL and port and <your-token> with the bearer token from the server Mac's settings. Consult the documentation for other MCP-capable applications.

And for other applications, you may need to edit a configuration file, either manually or via the client's settings. Again, consult its documentation.

Controlling MCP's Behavior

When you start using the MCP server, you may be prompted to allow access to certain locations. You may also be asked to allow use of the MCP tools. This behavior will vary, depending on the client application. We will use Claude Desktop as an example.

The first time Claude uses a specific tool, you will be asked to allow the behavior. Choose Allow Once or Always Allow, whichever you're comfortable with. However, you can not only view but also control access or prohibit certain functions from the MCP server.

Step 1: In the Claude application, choose Claude > Settings or press ⌘,.
Step 2: Click Connectors and you should see, e.g., DEVONthink LOCAL DEV. Tap the Configure button.
Step 3: Here you can view the list of commands available. For a specific command, click the encircled checkmark icon to always allow, the hand icon to require permission, and the circle-backslash icon to block the command entirely. Optionally, you can choose one setting for all commands via the Custom popup menu, e.g., always allowing all of them.