Connect an AI agent with MCP

Model Context Protocol (MCP) lets an AI client use tools from another app. Ligature provides search and reading tools for one approved library. With separate write permission, agents can create and append documents, create folders, labels, and saved views, move documents, and create, reply to, or resolve notes. They cannot replace existing document text, delete documents, assign labels to documents, or manage Sync.

Use the Ligature desktop app and an MCP client running on the same computer. The endpoint is http://127.0.0.1:47321/mcp and uses Streamable HTTP with a Bearer Authorization header. Keep Ligature open and the approved library active. A cloud session or a client on another computer cannot reach this loopback address.

You do not need Ligature Sync or a Ligature account. Your AI client may still need its own account and internet connection, and may send retrieved document content to its model provider. Connect only clients you trust.

Access is off by default. Enabling library access starts read-only. Existing connections also remain read-only until you explicitly enable write permission.

1. Open the library you want to connect.
2. Open Settings → AI → Agent Access and turn on Enable library access.
3. If you want the agent to write, turn on Allow changes to this library. Leave it off for read-only access. Set permissions before copying the configuration.
4. Choose Copy connection configuration. It includes the endpoint and an Authorization value beginning with Bearer.
5. Use the matching client instructions below. Replace YOUR_LIGATURE_TOKEN with only the token after Bearer in the copied configuration. Do not include Bearer twice.
6. Treat the copied configuration like a password. Keep it out of shared files, screenshots, source control, and support messages.

Allow changes to this library is separate from Enable library access. Turning write permission on or off replaces the token. Choose Copy connection configuration again, update the token in each client, and reconnect it. The endpoint and client configuration format stay the same.

Write tools are only available when write permission is enabled. Approving a different library starts read-only. Reset connection token preserves the current library’s permissions but replaces its token.

Saved write grants from before note tools were added revert to read-only. Turn Allow changes to this library on again to approve the expanded scope, then copy the new token into each client.

Disconnect revokes access. New and queued writes are blocked after revocation; a write already committing finishes its save operation. Review recent document history if an agent was writing when you disconnected.

With Claude Code installed, run the command below after replacing the token placeholder. User scope keeps this connection in your personal configuration rather than a shared project file. The command contains your token, so be mindful of shell history.

Start or restart Claude Code, then run /mcp to inspect the ligature connection. Approve the tools you intend to use when prompted. After changing Ligature permissions, replace the saved token and reconnect to refresh the available tools. If ligature already exists, update its saved configuration rather than adding a duplicate.

claude mcp add --transport http --scope user ligature http://127.0.0.1:47321/mcp --header "Authorization: Bearer YOUR_LIGATURE_TOKEN"

• Claude Code MCP documentation

For Claude Desktop's local command-based configuration, this example uses mcp-remote, a third-party bridge from stdio to HTTP. It is separate from Ligature and requires Node.js with npx available. The first launch downloads the bridge package.

Open Claude Desktop Settings → Developer → Edit Config. Merge the ligature entry below into the existing mcpServers object, preserving your other servers. Replace the token placeholder, save, and fully quit and reopen Claude Desktop. Check the connection in Developer settings or the conversation's Connectors menu.

This file stores your token locally in plain text. Keep it private. The Authorization argument deliberately has no spaces; the environment value includes Bearer followed by one space and your token. Do not paste Ligature's HTTP configuration unchanged into a command-based entry.

This is a local Desktop setup, not a claude.ai web connector. If npx cannot be found, check your Node.js installation and use the executable's full path in command.

{
  "mcpServers": {
    "ligature": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:47321/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${LIGATURE_AUTH_HEADER}"
      ],
      "env": {
        "LIGATURE_AUTH_HEADER": "Bearer YOUR_LIGATURE_TOKEN"
      }
    }
  }
}

• Claude Desktop local server setup
• mcp-remote bridge documentation

Add this table to your personal ~/.codex/config.toml, replacing the token placeholder. On Windows, use .codex/config.toml in your user profile. Preserve your existing settings and update an existing ligature table instead of creating a second one.

Restart your local Codex client after saving. This example stores the token as a private, static Authorization header; do not commit the file. For a CLI environment that supplies secrets, you can replace http_headers with bearer_token_env_var = "LIGATURE_MCP_TOKEN" and provide the raw token in that environment variable before launching Codex.

Use a local session on the computer running Ligature. Cloud or remote execution cannot reach this local endpoint.

[mcp_servers.ligature]
url = "http://127.0.0.1:47321/mcp"
http_headers = { Authorization = "Bearer YOUR_LIGATURE_TOKEN" }

• Official OpenAI documentation: MCP configuration

Ask your client: “Use Ligature to find my Agenda document and summarize its open tasks.” Choose a document you know exists in the approved library. If asked, approve the search and read tools.

Reading tools are documents_search, documents_list, documents_read, folders_list, labels_list, views_list, and comments_list. Archived documents and folders are excluded. Reads use saved library content, so unsaved editor drafts are not exposed.

With write permission enabled, ask: “Create a document titled MCP connection test with a short checklist.” Check the new document in Ligature. You can then ask the agent to read that document and append another checklist item. These actions change your library.

Write tools are documents_create, documents_append, folders_create, labels_create, views_create, documents_move, comments_create, comments_reply, and comments_resolve. Create accepts a title, Markdown content, and an optional folder ID. Append adds Markdown after existing blocks without replacing them. Moves and note writes require the document’s current revision from a fresh read. Each write accepts up to 100,000 characters of content; titles can contain up to 500 characters.

Agent writes follow the library’s normal save and Sync path. Document history identifies them as MCP agent with the device name. To review an unwanted change, open the document’s actions menu, choose Document history, and inspect an earlier version before restoring it.

Before appending, moving, or writing a note, the agent must read the document and pass its current revision as expectedRevision. A stale revision is rejected so a change is not silently applied against an outdated version. Read again and review the latest content before retrying.

Do not blindly repeat a failed create or append request. An error can occur after a change has been saved. Search or list documents after a create error, or read the document after an append error, to check whether the change already happened. Repeating a successful write can create duplicates.

Only one library can be approved at a time. Switching to another library suspends reads and writes; reopening the approved library restores them. To approve a different library, enable access for that library, choose its write permission if needed, and copy the new configuration into your client.

Choose Disconnect in Agent Access to revoke access. Changing write permissions, resetting, or re-enabling access replaces the token, so update every connected client afterward. Removing a server from one client does not revoke its token in Ligature.

Quitting Ligature stops the endpoint. The approved library, permissions, and securely stored token survive restarts; reopening Ligature with the approved library restores the connection.

Connection refused: open Ligature, check Agent Access is enabled, and confirm both apps run on the same computer. Use the exact endpoint shown in Settings. A container, virtual machine, WSL instance, or remote host may have a different loopback network.

Unauthorized: copy the current configuration again. Confirm the header is named Authorization and its value is Bearer followed by one space and the current token. Ligature uses this token rather than an OAuth login.

Wrong or unavailable library: open the approved library, or explicitly enable access for the library you want. Empty search results can also mean the document is archived or your latest text is not saved yet.

Write tools missing: confirm Allow changes to this library is on for the active, approved library. Copy the new configuration after changing permissions and reconnect your client. Existing read-only connections are not automatically upgraded. Older write grants may need re-enabling after note tools were added.

Append or note write rejected: read the document again to obtain a fresh revision and check whether the change was already applied. Do not retry blindly. Agents cannot replace existing text or write to archived documents.

Restoration failed: check Settings for the error. If the OS credential store is locked, unlock it and try again. If port 47321 is occupied, close the conflicting service; Ligature does not choose a random replacement port.

Still stuck: contact hello@useligature.com with your operating system, client name and version, and error text. Remove access tokens and private document content before sharing logs or screenshots.