Connect your AI

Connecting your AI links an external model — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, or any other MCP client — directly to your vault, so it answers from your notes on your own subscription. Altretta exposes your vault over the Model Context Protocol (MCP); the AI reads it through a small, local, token-protected endpoint that never leaves your machine.

Altretta ships no LLM. You bring your own model and pay your own provider. Nothing about your vault is uploaded to Altretta — the connection is local, and the AI is your AI.

One-click connect

Altretta detects the MCP clients you already have installed, sets up a scoped access token, and writes the client's configuration for you.

Open AI & connections

Go to Settings → AI & connections. Altretta scans for supported MCP clients on your system.

Pick a client

Choose the client you want to connect. Altretta detects and configures Claude Desktop, Claude Code, Cursor, VS Code and Windsurf automatically, minting a scoped access token and writing the client's config in one click. Any other MCP client can be pointed at the same endpoint by hand.

Ask a grounded question

Restart or reload the client and ask it something about your notes. It will query your vault first and answer with citations. See Grounded, cited answers.

Connect as many clients as you like

You aren't limited to one AI. Wire up Claude Desktop, Claude Code, Cursor, VS Code and Windsurf side by side — each gets its own one-click setup and its own named MCP token, so every connected client is independent and identifiable. Switch between them freely; they all read the same vault through the same grounded, query-first protocol.

How the connection works

Under the hood, the client talks to a local MCP endpoint:

http://127.0.0.1:19191/mcp

Requests carry a bearer token that Altretta creates for you in the app. Because the endpoint is bound to your own machine (127.0.0.1), it isn't reachable from the network — the AI reaches your vault, and nothing else does.

Access tokens you control

Tokens live under Settings → AI & connections → Access tokens. Altretta uses one token per runtime, so each connected client is independent.

Scoped

Each token grants access to your vault through the MCP tools and nothing more.

Per-runtime

One token per client. Claude Desktop and Cursor get their own tokens, so you can see exactly what's connected.

Named

Each token carries its own name, so you can tell at a glance which client — Cursor, Claude Code, Windsurf — holds it.

Revocable — one or all

Revoke a single token to disconnect one client while the rest keep working, or revoke everything at once for a clean cut.

Local

Tokens authenticate calls to a loopback endpoint on your own computer, not a cloud service.

Sharing a machine, or done with a client? Revoke its token — the others keep working. Need to cut everything off in one move? Revoke all tokens at once.

Connector permission policy

Beyond who is connected, you control what the tools may do — in the Trust panel (Trust · what your AI sees in the command palette). Two controls matter here:

Access level. Read-only is the default and the safe one: every writing tool is refused outright, so a connected client physically cannot change your vault. Read & write unlocks them.
Excluded folders. Any folder you list is never shared with your AI. Matching is by whole path segments, so Personal/Finance hides that folder and everything under it, but not a sibling called Personal/Finance2.

If you grant read & write, most writing tools take effect immediately. Only the propose a note tool routes through the Review inbox for your approval; editing a note, adding or removing tags, creating a folder, writing triples or running an ingest do not. Grant it deliberately.

What the AI can do once connected

Connecting gives the model a query-first, grounded view of your vault. It doesn't get a dump of your files — it gets tools to ask your vault questions and receive cited passages back:

aingle_ground — the core tool: returns cited passages as source:lines, a signed provenance anchor, a groundedness verdict, and an instruction the model must follow when answering.
aingle_sources — list the ingested source files with their content hashes: the signed provenance registry.
aingle_note_context — the notes semantically related to a given note, by meaning rather than by explicit links.
aingle_vault_map — get a map of your vault's structure and topics.
aingle_backlinks — a note's backlinks, its outgoing links, and unlinked mentions of it.

See Grounded, cited answers for what those citations look like, and What your AI sees for the controls over what you expose. The full set is documented in the MCP tools reference.

If you've ingested a codebase, its tools live on a second endpoint, http://127.0.0.1:19191/mcp-code, alongside the first. Point your client at that one too if you want it to answer questions about your code.

Next step

Connected? → Grounded, cited answers. Prefer to ask questions inside Altretta without an external client? That works too — the in-app Ask panel and Chat are grounded the same way.

AI you can trust

Back to the AI section overview.

Review inbox

Approve or reject the notes a connected AI proposes — and what the inbox does not cover.

AI profiles

Bring your own model for the in-app Ask panel and Chat — the other way to answer from your vault.

MCP tools reference

Every tool a connected client can call, listed and explained.

Team encryption

How access stays scoped and revocable when a vault is shared across a team.

Glossary

MCP, tokens, grounding — the connection terms, defined.