Agent access (MCP) · Teserra Docs

In short

Open Settings›Add-ons›Agent access and switch it on.
Pick your client, Copy the line, run it once in a terminal.
In Claude Code, type /mcp__teserra__taste and the name of a collection.

Turn it on

Pick your client, copy one line, and your agent can see your library.

Open Settings›Add-ons›Agent access and switch it on. The server listens on 127.0.0.1:8788/mcp and nowhere else.
Under Connect an agent, pick your client and Copy: the app's version carries your token. Here is what it looks like for each:

Run it once in a terminal. --scope user reaches Teserra from every project, not only the folder you ran it in.

claude mcp add --scope user --transport http teserra http://127.0.0.1:8788/mcp --header "Authorization: Bearer <your token>"

Codex reads the token from an environment variable: take it from the app's Other clients setup. Put the first line in your shell profile (~/.zshrc), then run the second once. Not yet tested end to end by us: tell us how it goes.

export TESERRA_TOKEN="<your token>"
codex mcp add teserra --url http://127.0.0.1:8788/mcp --bearer-token-env-var TESERRA_TOKEN

In Raycast, Manage MCP Servers, then Install from JSON. Then type @teserra in Raycast AI.

{
  "mcpServers": {
    "teserra": {
      "url": "http://127.0.0.1:8788/mcp",
      "headers": { "Authorization": "Bearer <your token>" }
    }
  }
}

Cursor, Zed, ChatGPT Desktop and the other clients that read this shape from their MCP settings.

{
  "mcpServers": {
    "teserra": {
      "type": "http",
      "url": "http://127.0.0.1:8788/mcp",
      "headers": { "Authorization": "Bearer <your token>" }
    }
  }
}

The token is the same one the browser extension uses.

Ready-made commands New in 1.3.12

In Claude Code, type /mcp__teserra__ and pick one. Each runs the right tools in the right order.

Type	What your agent does
`/mcp__teserra__taste Dark_Futurism`	Looks at a collection and writes its taste: colours with hex values, type, layout, details, what to avoid. Then saves it in Teserra. Start from an idea instead: `settings_page`.
`/mcp__teserra__use_taste Dark_Futurism`	Inside a project, turns the written taste into the art direction and the design tokens of the work in progress.
`/mcp__teserra__catalog 20`	Reads the pictures that have no description yet and writes title, description, tags and visible text, with its own vision. No AI key in Teserra.
`/mcp__teserra__constellation settings_page`	Draws what belongs together across your library, from an idea or from item ids (`12,45,78`).

NeedsAllow changes for taste and catalog, which save into your library. Visual search, installed in Settings›Add-ons›Visual search, for constellation.

One word per argument. Claude Code passes only the first word of each argument. Write Dark_Futurism for Dark Futurism; the start of a name, like Typo, is enough when only one collection begins that way. When a word starts several names, the agent asks which one you mean.

/mcp__teserra__catalog 6, on a real library

Your taste, written once New in 1.3.12

A written taste lives next to its collection in your vault, as a plain Markdown file. Any agent reads it back with its reference pictures, so the next landing page, deck or screen starts from your look instead of the usual AI default. Collections that have one are marked in list_collections.

/mcp__teserra__taste, then /mcp__teserra__use_taste

What agents can read

Library overview, collections, tags, the items of a scope (including the ones with no description yet), one item's full record, its image, a contact sheet of up to 30 numbered thumbnails, search by meaning, similar items, the written taste of a collection, and a constellation: from a few items or an idea, what belongs with them across the whole library, with the style words and the palette they share. Constellation runs on the local visual model, with no AI key. The same constellation is in the app: see Finding things.

What agents can change, if you let them

Switch on Allow changes, on the same page. Off, agents only read.

Tags: add, remove, rename, merge.
Collections: add to, remove from, create.
Items: titles, descriptions, ratings; describe pictures that have none (a note you wrote is never overwritten).
New things: import a URL, save the taste of a collection.

Never the trash: an agent cannot delete an item. Every change an agent makes to your items enters your undo stack: ⌘Z in Teserra takes it back. A URL it imported is a new item: move it to the Trash if you do not want it.

Activity

The same page lists the latest calls under Activity: which tool, with what, when, for the current session. Nothing an agent does is invisible.

Ideas. Write the taste of your best collection, then ask Claude Code for a pricing page after /mcp__teserra__use_taste. Let it describe a thousand screenshots on your plan while you work. Have it merge duplicate tags, then check the result in the grid. More requests to copy

PreviousFinding things NextThings to ask your agent