# Agent access (MCP)

Teserra can serve your library to Claude Code, Raycast, Cursor or any MCP client, on your Mac only. Your agent brings the intelligence on your own AI plan; Teserra brings the pictures, your taste and the memory. Off by default, every change undoable.

*Written from Teserra 1.3.16.*

**In short**

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

## Turn it on

[Clip: Settings, Add-ons, Agent access: the setup switches from Claude Code to Raycast and Other clients and back, then the Copy button turns to Copied.](https://teserra.app/assets/snips/agent-access.mp4)

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

**Claude Code**

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**

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
```

**Raycast**

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**

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`). |

**Needs:** **Allow 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.

[Clip: In Claude Code, /mcp__teserra__catalog 6. In Teserra, six pictures marked No description get a title, a description and tags, one after the other.](https://teserra.app/assets/tour/catalog.mp4)

## 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`.

[Clip: In Claude Code, /mcp__teserra__taste Dark_Futurism looks at the collection through Teserra and writes its taste: mood, colours with hex values, type, what to avoid. It is saved next to the collection; /mcp__teserra__use_taste then builds a pricing page in that look.](https://teserra.app/assets/tour/taste.mp4)

## 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](https://teserra.app/docs/search#constellation).

## 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](https://teserra.app/docs/prompts)