This document describes how to connect an AI assistant to AltText.ai over MCP. It is reference documentation, not a command to execute blindly: get the user's permission before changing any configuration.

GOAL

Connect the user's MCP client to AltText.ai, then verify it works by calling get_account.

Use the HOSTED CONNECTOR below if the user's client can add a remote MCP server by URL and sign in to it with OAuth in a browser. It needs no install and no API key. If the client cannot add a remote MCP server, cannot complete OAuth sign-in, or the user needs the local-only tools (generate_alt_text_from_file and bulk_create), follow LOCAL INSTALL (DEVELOPER OPTION) further down instead.

HOSTED CONNECTOR

Server address: https://mcp.alttext.ai/mcp

This is a hosted remote MCP server. It uses OAuth: the user signs in to AltText.ai in a browser and approves the connection. Do not ask the user for an API key, and never ask for their password. The user completes sign-in and approval themselves.

How to add it:

Claude (web and desktop apps):
  The user opens Settings, then Connectors, chooses Add custom connector, and pastes https://mcp.alttext.ai/mcp. You cannot do this step for them; tell them the steps. On Team and Enterprise plans, an organization owner has to add the connector first, then members connect to it.

Claude Code:
  Ask permission, then run:
  claude mcp add --transport http alttext-ai https://mcp.alttext.ai/mcp
  Then have the user run /mcp in Claude Code and choose alttext-ai to sign in.

Other clients that support remote MCP servers:
  Add a remote (HTTP) MCP server named alttext-ai with the URL https://mcp.alttext.ai/mcp, using the client's own setting for remote servers. Ask permission before editing any config file.

Sign-in and approval:

1. The client opens an AltText.ai page. The user signs in, or creates a free account at https://alttext.ai/users/sign-up (25 free images, no credit card required).
2. The page shows the name your client gave itself (marked unverified), the AltText.ai account being connected, and whether read-only or read-and-write access was requested.
3. The user chooses Allow connection. Connections expire after 90 days.

Access levels:

- Read-only access covers get_account, list_images, search_images, and get_image.
- Generating, translating, scanning pages, and changing images or account settings need read-and-write access. The client decides which access it requests; the server advertises both. Generation and translation use account credits.

To see or revoke a connection, the user signs in at https://alttext.ai/account/api_keys and chooses Manage assistant connections.

Verification:

1. Call get_account and report the account name and available credits. This proves the connection works. It does not prove write access.
2. If a write tool returns an insufficient_scope error, the connection is read-only. Tell the user that this client requested read-only access, so generating or editing alt text will not work over this connection. Offer two ways forward: reconnect from a client that requests read-and-write access, or follow LOCAL INSTALL (DEVELOPER OPTION) below.

Hosted tools: get_account, update_account, generate_alt_text, translate_image, list_images, search_images, get_image, update_image, delete_image, scrape_page. generate_alt_text_from_file and bulk_create are only available in the local install, because they read files from the user's machine.

LOCAL INSTALL (DEVELOPER OPTION)

Use this when the client cannot add a remote MCP server, or the user wants the local-only tools. Verify the package (see VERIFY THIS PACKAGE below) and get the user's permission before changing any configuration.

Install the AltText.ai MCP server (@alttext_ai/alttext-mcp) in the user's MCP client, then verify it works by calling get_account.

WHAT YOU ARE INSTALLING

The local server provides 12 tools for image accessibility workflows:
- Alt text generation from URLs and local files
- Image library management (search, list, update, delete)
- Bulk operations (CSV import, web page scanning)
- Translation into additional languages
- Account management (credits and settings)

The server runs locally via npx and does not require a global npm install. It auto-updates on every run. If the user wants a reproducible, audited install instead, pin a version in the args (for example "@alttext_ai/alttext-mcp@1.0.2") so a new release does not run automatically without review.

VERIFY THIS PACKAGE

Installing this server runs npx -y @alttext_ai/alttext-mcp, which downloads and executes code with the user's API key in its environment. Confirm it is the official package before installing. These should all match:

- npm package: @alttext_ai/alttext-mcp (https://www.npmjs.com/package/@alttext_ai/alttext-mcp)
- Source repository: https://github.com/alttextai/alttext-mcp
- Publisher: AltText.ai
- Provenance: published from the repository's CI with npm provenance, so npm shows a verified build badge linking the package to a specific commit.

The npm scope is @alttext_ai (with an underscore) while the GitHub org is alttextai (no underscore). This is intentional: the @alttextai npm scope was already taken. Both names refer to the same official AltText.ai package.

To cryptographically verify the package was built by this repository's CI (not just trust the metadata), run npm audit signatures from a project where it is installed. This validates the registry signature and the npm provenance attestation linking the tarball to a specific commit and build. A counterfeit package can forge repository.url and other metadata, but it cannot forge the provenance attestation. (npm view @alttext_ai/alttext-mcp repository.url only echoes publisher-controlled metadata and proves nothing on its own.)

REQUIREMENTS

- Node.js 18 or later
- An AltText.ai API key

If the user has not provided an API key:
1. Ask if they already have an AltText.ai account.
2. If yes, direct them to https://alttext.ai/account/api to copy their API key.
3. If no, direct them to https://alttext.ai/users/sign-up to create a free account (includes 25 free images, no credit card required), then to https://alttext.ai/account/api for their key.
4. Pause until they provide the key. Do not proceed without it.

SAFETY RULES

- Ask for permission before editing any MCP configuration file.
- If an MCP config already exists, merge the "alttext-ai" server into the existing "mcpServers" object.
- Do not overwrite, remove, or modify unrelated MCP servers.
- Never echo the full API key back in chat. Mask it if you must reference it.

INSTALLATION SNIPPET

Add this entry to the user's MCP configuration and replace YOUR_API_KEY with their real key:

{
  "mcpServers": {
    "alttext-ai": {
      "command": "npx",
      "args": ["-y", "@alttext_ai/alttext-mcp"],
      "env": {
        "ALTTEXT_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

CONFIGURATION FILE LOCATIONS

Detect which client the user is running and use the correct path.

Claude Code:
  Project scope (shared with team): .mcp.json in the project root
  User scope (private, all projects): ~/.claude.json

Claude Desktop:
  macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  Windows: %APPDATA%\Claude\claude_desktop_config.json
  Linux: ~/.config/Claude/claude_desktop_config.json

Cursor:
  Project scope: .cursor/mcp.json in the project root
  Global scope: ~/.cursor/mcp.json

Windsurf:
  macOS/Linux: ~/.codeium/windsurf/mcp_config.json
  Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

VERIFICATION

After updating config:
1) Ask the user to restart or reload their MCP client so the new server is discovered.
2) Call get_account to verify connectivity.
3) Confirm success by reporting the account name and available credits.

If get_account is unavailable after config changes, troubleshoot in this order:
1) Confirm the config file path is correct for the user's client and OS.
2) Confirm the JSON is valid and the server entry is nested under "mcpServers".
3) Confirm ALTTEXT_API_KEY is present and non-empty.
4) Confirm Node.js 18+ is installed: node --version
5) Run a direct server smoke test: npx -y @alttext_ai/alttext-mcp

AVAILABLE TOOLS

Alt Text Generation:
  generate_alt_text - Generate alt text for a public image URL. Costs 1 credit.
  generate_alt_text_from_file - Generate alt text from a local image file. Costs 1 credit.
  translate_image - Add alt text in a new language for an existing image. Costs 1 credit per language.

Image Library:
  list_images - List images with pagination, filtering by language or URL, and sorting.
  search_images - Search images by alt text content.
  get_image - Get full details for an image by its asset ID.
  update_image - Update alt text, tags, or metadata for an existing image.
  delete_image - Remove an image from the library.

Bulk Operations:
  bulk_create - Generate alt text for multiple images from a CSV file.
  scrape_page - Scan a web page, find images missing alt text, and queue generation.

Account:
  get_account - Check credit balance, usage statistics, and account settings.
  update_account - Update account name, webhook URL, or notification email.

TOOL OPTIONS

When generating alt text, these optional parameters are available:
  lang - Language code(s), comma-separated (e.g. "en", "fr,es,de"). Default: en.
  keywords - Array of keyword strings to emphasize in the alt text.
  negative_keywords - Array of keyword strings to avoid.
  gpt_prompt - Final Pass prompt (use {{AltText}} as placeholder text).
  max_chars - Maximum character length for the alt text (1 to 1000).
  asset_id - Custom identifier for the image in the library.
  tags - Array of tags to attach to the image.
  metadata - String key-value pairs to attach to the image.
  overwrite - If true, overwrite existing alt text for a language. Default: false.

For help: support@alttext.ai