Connect Claude

Overview

AMS exposes your business data to Claude through the Model Context Protocol (MCP) — an open standard Anthropic created so AI assistants can talk to external systems. Once connected, Claude can answer questions about your products, retailers, leads, and sales without you having to copy-paste data.

Connecting takes about a minute and works the same in Claude.ai web, Claude Desktop, and Claude Code: you add AMS as a connector and approve it once in your browser — there's no token to copy or paste, and Claude refreshes its own access after that. Building an integration or a scripted/headless setup? A long-lived static token is still available — see Advanced: Static Token.

Before You Start

• You must be a business admin in AMS to approve a connection (or generate a static token). (Employees can be granted MCP access in a future update.)
• Your AMS subscription must be active or in trial. Canceled or past-due accounts won't be able to authenticate.
• Claude.ai web, Desktop, and Code are all supported. All three connect through a one-click browser approval (no token to paste); a static token is still available for CI and scripted setups.

Connect Claude.ai Web

Claude.ai web connects to AMS as a custom connector — no token to copy. You approve the connection once in your browser, and Claude refreshes its access automatically after that.

1. In AMS, open Integrations → Claude → Overview and copy the MCP server URL from the Connect with Claude panel.
2. In Claude.ai, go to Customize → Connectors → + Add connector → Add Custom Connector and paste the URL. Leave the OAuth Client ID/Secret fields (under Advanced) blank — claude.ai registers itself automatically.
3. Claude sends you to an AMS approval screen. Confirm the business and scopes, then click Allow. You'll land back in Claude with AMS connected.

Only a business admin can approve the connection, and your subscription must be active or in trial — the same rules as generating a token.

Connect Claude Desktop

Claude Desktop connects the same way as the web — through a one-click browser approval, with no config file to edit and no token to paste.

1. Copy the MCP server URL from Integrations → Claude → Overview — the same URL the web uses.
2. In Claude Desktop, open its Connectors settings and choose Add custom connector, paste the URL, and leave the OAuth fields blank.
3. Approve the AMS connection in your browser when Claude opens it, then return to Desktop — AMS is connected.

Prefer the old config-file method, or running headless? You can still wire Desktop up with a static token and mcp-remote — see Advanced: Static Token below.

Connect Claude Code

From a terminal, add AMS with a single command — no config file, no token:

claude mcp add --transport http ams https://app.artistmanagementstudios.com/api/mcp

The first time Claude Code uses the connection it opens your browser to the AMS approval screen. Confirm the business and scopes, click Allow, and the next session has access to your AMS data. Scripting against a token instead? See Advanced: Static Token below.

Advanced: Static Token (scripts & automation)

The browser-approval flow above is the right choice for almost everyone. A static token— a long-lived personal access token — is for cases where an interactive browser approval isn't practical: CI jobs, scripts, headless servers, or pinning a specific set of scopes. It grants the same access, authenticated with a bearer token you paste yourself instead of an OAuth approval. You must be a business admin and your subscription must be active or in trial.

Generate a token

1. From any AMS dashboard page, open Integrations → Claude → Tokens.
2. Click Generate token.
3. Give the token a memorable name (e.g., "CI pipeline" or "Backup script") so you can identify it later in the list.
4. Choose your scopes. The picker groups them by area:
   • Read access — search and view your business data (Leads, Retailers, Products, Sales, and more). Core reads are pre-selected; at least one read scope is required.
   • Write & archive access— opt-in, per area. Lets Claude create, update, or archive records in that area (for example create a lead or log outreach). Conversion flags stay off — Claude can't accidentally convert a lead into a retailer.
   • Sensitive— change history (other people's edits, including names and financials). Off by default.
   Grant only what this connection needs — you can revoke and re-issue any time.
5. Click Generate token. AMS will show you the plaintext token once. Copy it immediately.

Important:The full token is only displayed at creation time. AMS stores a one-way hash, so we can't recover the plaintext later. If you lose the token, revoke it and generate a new one.

Use it with Claude Desktop (mcp-remote)

Claude Desktop only supports local-subprocess (stdio) MCP servers in its config file, so we use mcp-remote — Anthropic's small npx-launched bridge that connects Claude Desktop to a remote HTTP MCP server. The snippet in the modal already includes it; you don't need to install anything manually because npx grabs the package on first run.

1. Open Claude Desktop and go to Settings → Developer → Edit Config. This opens claude_desktop_config.json in your default editor.
2. Locate where the mcpServers block should live in your file:
   • If mcpServers already exists (you've connected another MCP server before), add "ams": {...} as a new entry inside that existing block.
   • If mcpServers does NOT exist yet (most common for first-time MCP users), add "mcpServers" as a top-level key — a sibling of any keys you already have like preferences. Separate it from the previous key with a comma. Don't wrap it in extra braces — that's the most common mistake.
3. Paste the JSON snippet from the Claude Desktop tab (pre-filled with your token) into the spot you identified above.
4. Save the config and restart Claude Desktop.

If Claude doesn't see AMS after restart, your JSON is most likely malformed. Common signs: an extra { before mcpServers, a missing comma between the previous key and mcpServers, or an extra } at the bottom. Run the file through a JSON validator (e.g. jsonlint.com) to spot the issue. The token-display modal's full-file example(under "Show full-file example") shows the exact placement.

Use it with Claude Code

Pass the token as an Authorization header instead of approving in a browser:

claude mcp add --transport http ams https://app.artistmanagementstudios.com/api/mcp \
  --header "Authorization: Bearer ams_pat_..."

Replace ams_pat_... with the token shown when you click Generate token.

What Claude Can Do

Claude has access to the following read tools:

• Search — find products, retailers, leads, podcasts, collabs, tasks, or events by name.
• Get record — fetch the full details of a single row, including key related data (e.g., a retailer with their recent orders and outreach history).
• List recent — see the most recent rows for any entity.
• Sales summary — total revenue, COGS, profit, and transaction count for the last 7, 30, or 90 days, or year-to-date.
• Top products— rank products by revenue, units, or profit over the same periods. Good for "what are my best sellers this month?" or "which products made the most profit last quarter?".
• Lead pipeline — leads grouped by status with last-touch dates and pending-outreach flags.
• Retailer relationship — a full retailer view: orders, outreach timeline, transaction history.
• Goals review — your annual revenue and metric goals for a year, each with year-to-date actual vs. target, percent to goal, months on track, the pace needed to finish, and a month-by-month breakdown — the same numbers as your Goals page. Claude can optionally reconcile your manually-entered revenue against what AMS recorded from transactions (wholesale, consignment, events). Great for prepping a year-end goals meeting.
• Describe entity — explain the fields of one entity (products, retailers, leads, and so on) so Claude knows how to read it.
• List capabilities— list everything Claude can do with your AMS in plain English. Ask "what can you do with my AMS?" and Claude will tell you.

When Claude connects, it first reads a small business manifest — a quick snapshot of your counts (how many products, retailers, open leads, upcoming events, and so on) and pointers to what it can do. It uses that to orient, then pulls only the specific records the conversation needs, so the connection stays fast and focused rather than loading your whole catalog up front.

Claude can also use a guided prompt, "Annual goals review", which walks it through pulling your goals and writing a meeting-ready executive report (what's on track, what's at risk, and recommended actions). In Claude Desktop you'll find it where the app lists prompts from connected servers.

With write scopes, Claude can also:

• Create lead — add a new lead from a conversation (e.g., after Claude helps you draft a cold-outreach email).
• Log outreach — record an outreach interaction against a lead, retailer, podcast, or collab.

Anything Claude creates is tagged with a Claude badge in the dashboard so you can always see what was added through the connection.

Shared Documents

With the documents scopes, Claude can read and write a shared, durable document store for your business — markdown documents like a brand guide, a yearly business plan, positioning notes, or its own running notes across sessions. Because the store lives in AMS, a document one assistant writes is readable by all of them — Claude Desktop, Claude Code, and claude.ai web — so your business context follows you instead of living in one chat history.

• documents:read — list, read, and full-text search your documents. The connection only loads a lightweight index up front (titles, types, tags) and fetches a full document body when it actually needs it.
• documents:write — create and update documents. Brand guide and business plan are kept to one each per business; everything else (notes, summaries) can be created freely.
• documents:archive — archive a document (a soft delete — it stays in version history).

The Documents tab on the Connect Claude page shows every document, its version history, and the rendered markdown. You can download any document as a Markdown (.md) file — from a row or from the document viewer — and when you're viewing an older version, the download saves that version. Documents are admin-only by default— the most sensitive ones (your business plan, strategy notes) stay with admins unless you mark a document team-visible. Markdown is always sanitized before it's displayed.

Managing Connections

On the Connect Claude page in your profile, the Tokens tab lists everything that can reach your AMS data. Each row shows:

• The name and the admin who created it
• The scopes granted
• The Source — Manual for a static token you generated yourself, or the connecting app's name (e.g. Claude.ai) for a connection you approved in the browser
• The token prefix (the first 12 characters of the plaintext)
• When it was last used
• When it was created

Any business admin can revoke any entry in the business — useful when a colleague leaves the company or if access is suspected of being compromised. Revocation is immediate.

You can have up to 25 active tokens per business. Revoking one frees the slot.

Activity Log

Switch to the Activitytab to see exactly what Claude has been doing on your business's behalf. Every tool call and resource read is logged with:

• The timestamp (in UTC)
• Which token made the call (and which admin owns it)
• A friendly action label ("Searched", "Created lead", etc.)
• The status (success, error, or denied)
• A one-line summary of the arguments

Filter by token, status, or date range. The activity log is business-wide — every admin sees the same data.

Security

• No token to leak.When you connect through the browser approval, Claude is issued a short-lived access token (1 hour) and a refresh token it rotates automatically — there's no long-lived secret for you to copy, store, or accidentally share.
• Tokens are stored as one-way hashes. AMS only stores a SHA-256 digest of each token, plus the first 12 characters for display. The plaintext token is never recoverable from our database.
• HTTPS only. All traffic to the MCP endpoint is over HTTPS. Never send a token over plain HTTP.
• Scope enforcement. Claude only sees the tools permitted by the granted scopes. Without write:leads, the create-lead tool isn't even visible to Claude.
• Per-token rate limits. Each token is capped at 60 requests per minute. Excess requests return a 429 with a Retry-After header.
• Revocation is immediate. Once revoked, the next attempt to use the connection returns 401.
• Multi-tenant isolation. Every query Claude runs is scoped to your business_id, derived from the verified token — never from anything Claude sends.

Troubleshooting

"Couldn't register" / the connector won't add — Make sure you pasted the exact MCP server URL from the Connect with Claude panel (it ends in /api/mcp) and left the OAuth Client ID/Secret fields blank. claude.ai registers itself automatically; filling those fields in can break the handshake.

401 Invalid or revoked token— The token doesn't match any active record. Either it was mistyped, revoked, or never copied correctly. Remove the connector and add it again to re-approve, or generate a fresh static token.

403 Subscription not active — Your AMS subscription is canceled or past due. Renew on the Subscription page and try again.

403 Tool requires scope — Claude tried to call a write tool, but the connection only has read. Re-approve the connection (or generate a new token) with the needed write scope.

429 Rate limit exceeded — More than 60 requests in a minute. Claude usually backs off automatically; if it persists, your usage is unusually heavy and may need investigation.

401 / "Server unavailable" in your Claude client — The MCP server returns a precise auth-error message in the WWW-Authenticate header and JSON body (e.g., "This token was revoked at..." or "Token not found..."), but some bridges hide that detail and just show "Server unavailable". If you're seeing the generic error and tool calls are failing, the most likely cause is a revoked or expired connection. Check the Tokens tab on Connect Claude — if it's marked Revoked, remove and re-add the connector.

Claude doesn't see the AMS tools— Restart Claude after connecting, or verify the URL matches what's shown in the Connect with Claude panel exactly. On claude.ai web, re-check the connector under Customize → Connectors and make sure you completed the AMS approval screen.

Claude Desktop shows "Some MCP servers could not be loaded" / "skipped: ams" — A static-token config likely has an old url+headersshape from an earlier version of these instructions. Claude Desktop's config file only accepts stdio configs, so the snippet must use command + args with mcp-remote. Generate a fresh token (or regenerate one) and copy the current snippet from the Claude Desktop tab — it uses the correct shape.