Developer Docs

MCP

Connect Claude, Codex, and other MCP clients to your Alt notes.

Alt ships a hosted MCP (Model Context Protocol) server. OAuth-capable clients can connect with browser sign-in; API keys remain available as a fallback. Both methods enforce the same read-only scopes and workspace boundary.

Start here

Run the interactive setup wizard to store your API key, connect MCP, and hand off to your agent:

npx
npx altalt --mcp-only

Connect with the Claude connector

Alt is listed in the Claude connector directory, so most people never touch the endpoint below. In Claude, open Customize → Connectors, search for Alt, and select Connect.

  • Approve access on Alt's own consent screen, and pick the content the connector may read — your personal notes, or a single channel.
  • Nothing to paste and no API key to create. Claude registers itself over OAuth.
  • Requires an Alt account on a paid plan. Free accounts reach the consent screen but get a plan_required error when they approve.
  • Read-only by design: it lists and searches notes and reads transcripts and summaries, and never writes. Revoke it any time in the account console.
View in the connector directory

1. Connect with OAuth (recommended)

Add the endpoint without headers. Your client discovers Alt's authorization server, registers itself, and opens the browser consent screen.

  • Alt supports Dynamic Client Registration and PKCE, so compatible clients configure OAuth automatically.
  • Review the requested read-only scopes and workspace in the browser before approving access.
  • Connecting requires an Alt account on a paid plan. Free accounts reach the consent screen but get a plan_required error when they approve.

2. Connect your client

Use the URL-only setup for OAuth. No OAuth client ID or secret is required; use an API key only when your client cannot complete OAuth.

MCP URL
https://mcp.altalt.io/mcp

Claude / Claude Desktop / Cowork

Use a custom connector only to reach a different Alt environment: open Customize → Connectors → Add custom connector, enter the endpoint above, and leave the OAuth client ID and secret empty.

Claude Code

shell
claude mcp add --transport http alt https://mcp.altalt.io/mcp

After adding the server, open /mcp in Claude Code, select Alt, and complete browser authentication.

Codex CLI

shell
codex mcp add alt --url https://mcp.altalt.io/mcp
codex mcp login alt
config.toml
# ~/.codex/config.toml
[mcp_servers.alt]
url = "https://mcp.altalt.io/mcp"

Adding the server normally completes browser authentication. If authentication does not start, run codex mcp login alt.

Cursor

Add to Cursor

One-click URL-only install. In Cursor's MCP settings, select Connect or Needs authentication and approve the browser consent screen.

Other clients and API-key fallback

Start with the URL-only OAuth config. If a client does not support MCP OAuth, use the Bearer API-key config instead.

OAuth
{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp"
    }
  }
}
API key
{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp",
      "headers": { "Authorization": "Bearer alt_live_..." }
    }
  }
}

API keys remain supported for automation and older clients. Create one in the account console, grant only the scopes you need, keep it out of shared config, and see Security for key handling.

3. Tools

Seven read-only tools. They enforce the same scopes as the REST API.

  • list_notes — List the notes this connection can read, with cursor pagination. Oldest update first by default; pass order=newest_first for the most recent first. Filter by updated_after, recording end time (ended_after / ended_before), channel_id or folder_id (notes:read).
  • get_note — Fetch one note's metadata: title, transcript/summary readiness, timestamps (notes:read).
  • get_note_transcript — Fetch the full transcript as timed, speaker-labeled segments (transcripts:read).
  • get_note_summary — Fetch the AI summary as Markdown (summaries:read).
  • search_notes — Find notes whose title, transcript, or summary contains a word or phrase. Transcript hits include the time and speaker. Transcripts and summaries are searched only with transcripts:read / summaries:read (notes:read).
  • list_folders — List the folders this connection can read. A folder's id works as folder_id in list_notes (notes:read).
  • get_account_info — Show which Alt account the connection belongs to, whether it reads personal notes, one channel, or a whole workspace, and its readable channels and permissions. Useful when expected notes are missing (notes:read).

Notes appear once a recording has ended or a summary has been generated — memo-only notes are not exported. Before content is ready the tools return transcript_not_ready / summary_not_ready, so agents know to retry later.