AI tool connection and auto-logging (MCP)

Connecting an AI tool to MashNote means adding MashNote to that tool as a plugin, MCP connector, or MCP server and signing in. Once connected, the AI logs summaries of finished work as MashNote activity. It sends only work summaries, never raw conversations.

MCP (Model Context Protocol) is a standard that lets AI tools use features of outside services. This page calls it MCP from here on.

What the MashNote MCP tools do

MashNote’s MCP tools can log activity. The MashNote plugin for the ChatGPT desktop app and Codex CLI can also read notes in approved workspaces after you grant note-reading and workspace access through OAuth.

Tool	What it does
log_activity	Logs one activity entry.
list_workspaces	Looks up the names and IDs of your workspaces when choosing where to log.
list_recent_activity	Checks the entries you logged recently, so the same thing isn’t logged twice.
:::

Connecting and activating are separate steps

A successful connection and tool activation are different steps. After connecting, enable the MashNote tools in a new conversation or task before you can use auto-logging.

Before you start

Build your connection steps and prompt in MashNote’s AI tool connection (MCP) card.

1. Open your avatar at the bottom of the navigation rail (Account menu) and choose Settings.
2. In Personal settings, open the Integrations tab.
3. Expand the AI tool connection (MCP) card.

The card is laid out in this order:

Card section	Contents
1. AI tool to use	Pick ChatGPT, Claude, Cursor, Antigravity, or Other. For ChatGPT, also pick chatgpt.com or Desktop app; for Claude, Web & desktop app or Claude Code (CLI).
2. Product setup (the title changes with the product you pick)	Shows the MashNote MCP address or command to copy, plus install steps. Products that support both a settings screen and a CLI let you choose Settings screen or Set up via CLI. Detailed connection guide opens that product’s section on this page.
3. Verify tool activation	What to check in a new conversation after connecting. If something’s wrong, click Connected but no tools? Troubleshoot.
4. Auto-logging prompt	Pick a log destination and an English prompt is generated.
Advanced · direct connection	Connector address, issuing access tokens, and revoking connected clients and issued tokens

The card header shows the connection status. After you connect but before anything is logged, it shows Configured · no writes yet; once at least one entry arrives, it changes to Auto-logging confirmed · {date}.

The common connection flow

Menu names differ by product, but the steps are the same.

1. In the AI tool connection (MCP) card, check the installation steps for your AI tool.
2. Add MashNote to the AI tool as a plugin, MCP connector, or server. For the ChatGPT desktop app and Codex CLI, follow the marketplace installation steps below.
3. On the MashNote Approve connection page that opens in your browser, click Allow. See The Approve connection page.
4. Open a new conversation or task and enable the MashNote tools. Check that log_activity, list_workspaces, and list_recent_activity appear.
5. Paste the auto-logging prompt generated in the card into the AI tool’s instructions.

The Approve connection page

When you start the MashNote sign-in from an AI tool, MashNote’s Approve connection page opens in your browser. If you aren’t signed in to MashNote, you see the sign-in screen first and return to this page afterward.

• The heading shows the name of the app you’re connecting, as in Connect {clientName}.
• Review Requested permissions, including activity logging. When installing the MashNote plugin for the ChatGPT desktop app or Codex CLI, also approve note-reading access and the workspaces it may access.
• Click Allow to finish connecting and return to the AI tool. Click Deny to cancel the connection.
• If you see an Unverified app warning, the app’s name was self-registered by its developer and hasn’t been verified by MashNote. Make sure it’s the app you just started connecting from before you allow it.

Setup by product

ChatGPT

In the card, pick ChatGPT, then choose chatgpt.com or Desktop app.

chatgpt.com

1. In ChatGPT, turn on Developer mode under Settings → Apps → Advanced Settings.
2. Create a custom app under Apps → Create and enter the MashNote MCP address.
3. Finish Scan Tools and the OAuth login (MashNote Approve connection), then press Create to add the app.
4. Open a new conversation and pick the MashNote app from the tools menu.
5. Check that log_activity, list_workspaces, and list_recent_activity appear. If the tools are missing, refresh MashNote in the Apps settings and open a new conversation.

Note

Write tools on ChatGPT web may be limited by your plan and workspace policy. If log_activity isn’t in the tool list, see ChatGPT troubleshooting.

If you keep logging a specific workstream, we recommend putting the prompt in a ChatGPT Project’s instructions.

ChatGPT desktop app · Codex CLI

Add the marketplace, then install the MashNote plugin.

1. In plugin management in the desktop app or Codex CLI, choose to add a marketplace.

2. Enter this marketplace address:

   https://github.com/lymeric-ai/mashnote-plugin.git

3. Install the MashNote plugin from the added marketplace.

4. Start the installed plugin’s OAuth sign-in.

5. Sign in to MashNote in your browser.

6. Approve note-reading access and the workspaces the plugin may access.

7. Restart the desktop app. For Codex CLI, quit and start a new session.

8. Open a new conversation and select @MashNote.

9. Confirm that MashNote tools such as log_activity appear, then apply the auto-logging prompt.

If already installed, refresh the marketplace in the desktop app, then update or reinstall the MashNote plugin. Complete OAuth sign-in and note-reading and workspace approval, restart the app, and select @MashNote in a new conversation.

Put the prompt in Codex’s global instructions or in the project’s AGENTS.md.

Claude (web & desktop app)

In the card, pick Claude → Web & desktop app. A remote MCP connector added once works in both the Claude web and desktop apps.

1. In Claude, choose Add custom connector under Settings → Connectors.
2. Name it MashNote and enter the MashNote MCP address.
3. Press Connect to sign in (MashNote Approve connection), then check that the connection is active.
4. Open a new conversation and enable MashNote under Search and tools.
5. Check that log_activity, list_workspaces, and list_recent_activity appear. If permissions are on but tools are missing, reconnect MashNote under Connectors and open a new conversation.

active is the account connection status. You’re ready for auto-logging only after you enable MashNote in a new conversation and see the actual tool list.

Note

On Claude Team or Enterprise, an owner may need to add the connector to the organization first.

If you keep logging a specific workstream, we recommend putting the prompt in a Claude Project’s instructions.

Claude Code (CLI)

In the card, pick Claude → Claude Code (CLI) to see a Claude Code command with your MashNote MCP address filled in. It registers MashNote at user scope, so the same connection works in every project.

claude mcp add --transport http --scope user mashnote '<MASHNOTE_MCP_URL>'

1. Paste the command into a terminal to add a user-scoped MCP server.
2. Open Claude Code and start MashNote authentication from /mcp.
3. Finish the MashNote sign-in and approval in the browser, then return to Claude Code.
4. In /mcp, check that MashNote is connected. If a session was mid-connection, restart Claude Code to reload the tools.
5. Confirm log_activity and list_workspaces appear in a new task.

Put the prompt in your user CLAUDE.md (all projects) or the project’s CLAUDE.md.

Cursor

The Cursor IDE and Cursor CLI read the same MCP config. In the card, choose Settings screen or Set up via CLI.

Add it from the settings screen

1. Open Tools & MCP in Cursor Settings and add a new MCP server.
2. Name the server MashNote, set the type to Streamable HTTP, and enter the MashNote MCP address.
3. Finish the OAuth login (MashNote Approve connection) and refresh Available Tools.
4. Enable MashNote under Available Tools in Tools & MCP.
5. Confirm log_activity appears in a new Agent task.

Add it with mcp.json and the CLI

Add the following config to the global ~/.cursor/mcp.json or the project’s .cursor/mcp.json.

{
  "mcpServers": {
    "mashnote": {
      "url": "<MASHNOTE_MCP_URL>"
    }
  }
}

1. Run agent mcp login mashnote in the Cursor CLI to sign in.
2. Check that the MashNote tools appear with agent mcp list-tools mashnote.
3. Check that MashNote is connected with agent mcp list.

Put the prompt in Cursor’s user Rules or project Rules.

Antigravity

Antigravity desktop and CLI read the same MCP config. In the card, choose Settings screen or Set up via CLI.

Add it from the settings screen

1. Open Settings → Customizations → Installed MCP Servers.
2. Press Add MCP and enter the MashNote MCP address as serverUrl for a custom server.
3. On the added MashNote, press Authenticate and complete the browser sign-in (MashNote Approve connection).
4. Enable MashNote under Installed MCP Servers and press Refresh.
5. Confirm log_activity appears in a new task.

Add it with a config file and the CLI

Add the following config to the global ~/.gemini/config/mcp_config.json or the project’s .agents/mcp_config.json.

{
  "mcpServers": {
    "mashnote": {
      "serverUrl": "<MASHNOTE_MCP_URL>"
    }
  }
}

1. Open the Antigravity CLI and Reload the config from /mcp.
2. Select MashNote, finish authentication, then check the connection status.
3. Check MashNote’s status and tool list in /mcp.

Put the prompt in Antigravity’s global instructions or the project’s AGENTS.md.

Other MCP apps

In the card, pick Other. First check that your AI tool supports:

• remote Streamable HTTP MCP servers;
• OAuth sign-in (if it doesn’t, connect with an access token);
• refreshing the MCP tool list.

If it does, connect in this order:

1. Open the app’s MCP, Tools, or Connectors settings.
2. Add MashNote as a remote Streamable HTTP server and enter the MashNote MCP address.
3. Complete the OAuth login (MashNote Approve connection) and refresh the tool list.
4. Enable MashNote in the app’s tool list and check that log_activity and list_workspaces appear.
5. If tools are missing, reload the server or open a new conversation.

If your app supports user or project instructions, paste the auto-logging prompt there.

Verify tool activation

A Connected or active status alone doesn’t mean you’re ready for auto-logging. Check that the MashNote tools actually appear in a new conversation or task.

1. Open a new conversation or task.

2. Enable the MashNote tools yourself.

3. Refresh the tool list.

4. Check that these three tools appear:

   • log_activity
   • list_workspaces
   • list_recent_activity

5. Ask the AI: “Log one test activity to MashNote.”

6. Check that the test entry appears in MashNote’s My Mash. The AI tool connection (MCP) card status also changes to Auto-logging confirmed · {date}.

Caution

Without log_activity, auto-logging doesn’t work. See the symptom-based guide in Connection troubleshooting.

Auto-logging prompt

To have the AI log on its own whenever it finishes work, paste the prompt from the card’s 4. Auto-logging prompt section into the AI tool’s instructions. The prompt is generated in English.

1. Choose a Log destination. The default is Log to me only (default); you can also pick one of your workspaces.
2. Choose Where the prompt goes. Depending on the product, pick global (personal) instructions or project instructions. For Other, placement guidance appears instead of this field.
3. Optionally turn on Also show a copyable log for when the tool is unavailable.
4. Check the Preview and click Copy prompt.
5. Paste it into the location you chose.

The prompt body is one of two kinds, picked automatically by product, followed by a destination section.

Prompt	Used for
Chat AI	chatgpt.com, Claude web & desktop app
Coding tools	ChatGPT desktop app & Codex CLI, Claude Code, Cursor, Antigravity, Other

Below are the prompts generated with Log to me only (default). We recommend copying from the card, but the text below is identical.

Prompt for chat AI

MashNote is an append-only activity ledger exposed through the `log_activity`,
`list_workspaces`, and `list_recent_activity` connector tools.

## When to log
Proactively append one entry after a completed, meaningful work unit: a decision,
deliverable, agreement, or review with a conclusion. Do not log every turn, pure
exploration, trivial one-offs, or casual chat.

## What to write
- Capture the outcome and useful rationale, not the raw conversation.
- Use a short title, a concise summary, and optional points or markdown detail.
- Choose one to three short tags for the current line of work. Reuse the same tags
  on later entries while this thread continues that work; change them when the topic changes.
- Use one stable `idempotencyKey` per completed work unit.
- Never include secrets, credentials, card numbers, or national ID numbers.

## Tool behavior
- Actually call `log_activity` when it is available.
- Never claim a write succeeded unless the tool result confirms it.
- If the tool is unavailable, say so briefly. Only print a manual ledger entry if
  I explicitly ask for one.
- The ledger is append-only. Do not rewrite or organize earlier entries.

## Destination
Use the personal/default route and omit `workspaceId` when calling
`log_activity`. The server may apply a workspace connection I have already saved.
Do not call `list_workspaces` and do not ask me to choose a destination. Only pass an
explicit workspaceId when I request one in the current conversation.

Prompt for coding tools

## MashNote activity ledger

Use the MashNote `log_activity` tool to append concise records of completed
coding work. Log meaningful milestones, not every agent turn.

Log after a milestone such as:
- `decision`: an architectural or product choice with rationale
- `implementation`: a coherent change is complete
- `verification`: tests or review reached a useful conclusion
- `delivery`: a commit, pull request, or handoff is ready

Keep GitHub as the source of truth for code, diffs, commits, and pull requests.
MashNote should capture the background, tradeoffs, rationale, and outcome. Avoid
repeating long file lists or diff summaries already available in GitHub. If useful,
include `context.workUnitId`, `context.milestone`, and artifact references.

Choose one to three short tags for the current line of work and reuse them on later
entries in this thread. Change the tags only when the thread moves to different work.

Use a stable `idempotencyKey` per completed work unit. Send only summaries, never
raw transcripts or secrets. Never claim a write succeeded unless the tool confirms
it. If the tool is unavailable, say so briefly; only print a manual entry when I ask.

## Destination
Use the personal/default route and omit `workspaceId` when calling
`log_activity`. The server may apply a workspace connection I have already saved.
Do not call `list_workspaces` and do not ask me to choose a destination. Only pass an
explicit workspaceId when I request one in the current conversation.

Logging to a specific workspace

When you pick a workspace as the Log destination, the ## Destination section at the end of the prompt is replaced with that workspace’s exact name and ID. Because it contains the workspace ID, copy this prompt from the card. It looks like this:

## Destination
For this project, log MashNote activity to this exact workspace:
- Name: <WORKSPACE_NAME>
- workspaceId: <WORKSPACE_ID>

Pass this `workspaceId` directly to `log_activity`. Do not call
`list_workspaces` merely to confirm it, and do not ask me to choose a destination.
Only resolve it again if `log_activity` reports that the id is inaccessible, or if
I explicitly override the destination in the current conversation.

If you put a workspace prompt in global (personal) instructions, the card warns: Putting it in global instructions may log other conversations to this workspace too. To log only a specific project to a workspace, put it in project instructions such as:

• a ChatGPT Project’s instructions
• a Claude Project’s instructions
• AGENTS.md in a Codex or Antigravity project
• CLAUDE.md in a Claude Code project
• Cursor project Rules

Turning on Also show a copyable log for when the tool is unavailable adds the following sentence to the end of the prompt. When log_activity can’t be used, the AI shows you an entry you can copy instead.

If `log_activity` is unavailable, print a concise manual ledger entry for me to copy.

Where entries go and who sees them

Activity that arrives through MCP is logged just for you by default. It collects only in My Mash, with no workspace, and doesn’t appear in a team’s Activity feed.

There are three ways to send it to a workspace:

• Workspace link rule: in My Mash → Visibility & workspace links, set a default workspace link and visibility per source (for example, Claude Code or ChatGPT). Activity logged from that source after you set the rule is linked to that workspace.
• Per-item linking: in My Mash, select one or more logged entries and link them to a workspace, or set them back to Just for me.
• Workspace prompt: with the Logging to a specific workspace prompt, the AI logs to that workspace from the start.

For visibility and bulk organizing, see Activity and My Mash.

Advanced · direct connection

Expand Advanced · direct connection at the bottom of the card for:

• Connector address: the MashNote MCP address, for editing config files directly.
• Access token: a personal access token for apps or CI without OAuth login.
• Connected clients: AI apps connected through OAuth.
• Issued tokens: the access tokens you’ve issued.

Access tokens

1. Enter a token name. If you leave it blank, mashnote-pat is used. A distinct name per client makes them easy to tell apart later.
2. Click Issue token.
3. Copy the token that appears and keep it somewhere safe.
4. In the app’s MCP server settings, enter the MashNote MCP address and set the token as an authorization header in the form Authorization: Bearer <token>.

Danger

The token is shown only once, right after it’s issued, and can’t be viewed again. Keep it out of .env files, shell history, repositories, support requests, screenshots, and public issues.

Issued tokens shows each token’s name, prefix, expiry date, and last-used date. Tokens that go unused for a long time expire. Click Revoke to invalidate a token you no longer use right away.

Disconnecting

Connected clients shows each app connected through OAuth by its identifier (an address) and connection date. Click Revoke next to an app to disconnect it; shortly afterward, that app has to sign in again before it can log to MashNote.

• Connections are managed per app (client), not per AI account. If you signed in to the same app with several accounts, revoking disconnects them all.
• Revoking a connection doesn’t delete activity that’s already logged.

If you have trouble connecting or activating tools, see Connection troubleshooting.

Are you a developer?

To edit MCP config files directly or see technical setup and examples, visit the MashNote MCP GitHub repository.