AI-1685: add Amperity MCP integration docs#799
Merged
Conversation
Adds a new MCP section under amperity_api/ covering setup for Microsoft 365 Copilot, Claude, and ChatGPT, plus authentication, safety modes, a domain-grouped tool reference, and troubleshooting. Marked as beta in the overview. AI-1685 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the hand-waved "OAuth 2.0 with PKCE" step with the actual Copilot Studio MCP onboarding wizard flow per Microsoft Learn: - Lead with OAuth 2.0 > Manual as specified, with field order and exact labels from learn.microsoft.com - Document the post-Create callback URL step - Add a brief "Dynamic discovery" alternative since our server publishes OAuth metadata + supports DCR - Flag the client-secret-required-by-UI question for verification Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Keep the page focused on the Manual flow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Audited every tool name and claim against the live amperity-mcp source (commit da90b2c). Findings, all fixed: - Tool names use the domain.action convention (with dots), not domain_action -- matches name="..." values in server.py and the README's contribution standards. - Default safety mode is `strict` (server.py:371 _DEFAULT_SAFETY_MODE), not `confirm`. Updated table to mark strict as default and corrected semantics. - Removed AMPERITY_TENANT env-var advice from the auth page; that path is for the local stdio CLI mode, not the hosted HTTP server. - Removed the unverifiable "every tool call is logged" claim from the safety page (audit logging is still on the roadmap per the MVP plan). - Softened token claims to what's verifiable from outside: bearer required, validated against Auth0, refresh handled by the client. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copilot Studio is the authoring tool where the MCP connector is configured. Update all customer-facing references and the page title accordingly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Overview: clarify that some clients (e.g. Copilot Studio's 70-tool cap) surface a subset of the 200+ tool surface; soften "stateless" language since per-token session state (tenant, safety mode) does persist via Redis-backed session store. - Safety modes: add a note that the model is evolving and that the agent can self-elevate via safety.set_mode -- it is a guardrail, not an access boundary. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Convert every domain.action tool reference in the docs to domain_action to match the rename in amperity/amperity-mcp#401 (jborn). That PR renames every tool because Claude.ai and AWS Bedrock reject names containing periods. This docs PR is now blocked on amperity-mcp#401 -- merging it sooner would publish tool names that don't yet exist in prod. 271 replacements across 7 files; spans like ``domain_action`` only. URLs, ``tools/list``, file references, and the ``mcp.amperity.com`` host remain unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The standalone authentication page was protocol-level walkthrough that beta customers (Copilot Studio / Claude / ChatGPT) don't read. The discovery table already lives in mcp_connect, and the manual OAuth values live in mcp_setup_m365_copilot. Changes: - Delete mcp_authentication.rst (the one redundant page) - Remove its toctree entry from index.rst - Drop "Related topics" from mcp_overview (toctree provides nav) - Drop "Choose your client" from mcp_connect (already in overview) - Inline the authentication summary so it stands on its own - Fold "How to discover tools" into the tool reference intro Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces a hand-wavy "tool selection controls" bullet with the actual UI path per Microsoft Learn: agent Tools tab > MCP server > Tools section > Allow all toggle > individual tool toggles. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the "List my Amperity tenants" example -- which assumes multi-tenant customers and uses internal team voice -- with "Tell me about my Amperity tenant", which works for single- and multi-tenant customers and calls tenant_info to surface concrete data as a connection check. The troubleshooting "No tenant selected" example keeps the list/use flow because that section is specifically for multi-tenant customers who need to pick. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The HTTP server mounts the MCP handler at both /mcp and / (verified in http_server.py:75-76 and via curl POST). Amperity's own amperity-mcp/README.md documents the bare host form for Copilot Studio setup -- that's the form the team has actually tested. Switching all customer-facing MCP server URLs to the bare host form to match team convention. OAuth-specific paths (/authorize, /oauth/token, /oauth/register, /.well-known/...) keep their paths since those are distinct routes, not the dual-mounted MCP transport. 11 replacements across 5 files. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrite mcp_setup_claude.rst against Anthropic's canonical help docs and live-tested commands. Verified: - Claude Code flow tested in this session: `claude mcp add ...` registers cleanly, status shows "Needs authentication" until first authorized call, then transitions to "Connected". Corrected: - Claude Desktop section previously told customers to add a `url` entry to claude_desktop_config.json. Per Anthropic's docs that file is for local stdio servers only and does not handle remote MCPs. Remote connectors are managed via Claude.ai and propagate to Claude Desktop and the mobile apps via the user's account. Added: - Claude.ai is now the lead section, with separate Pro/Max (Customize > Connectors) and Team/Enterprise (Organization settings > Connectors, Owner-only) flows quoted from Anthropic's help center. - Note clarifying that Desktop inherits the Claude.ai config and does not require any local file edits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Merge the two parallel step lists into a single shared "then" block since the URL, click sequence, and OAuth result are identical. Pull the only difference -- where to start the Connectors page -- into a two-bullet split at the top. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The lead-in already states the Claude.ai connector flows into Desktop and mobile. The follow-up sentence introduced a config file only to tell readers not to use it -- noise for the beta audience. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ChatGPT's standard custom connectors are restricted; full MCP support including write tools is gated behind developer mode (Settings > Apps > Advanced settings > Developer mode). Since Amperity exposes write tools, developer mode is effectively required. Adds the prerequisite + the enable steps, and corrects the plan list to match what OpenAI documents (Pro / Plus / Business / Enterprise / Education on the web). Source: developers.openai.com/api/docs/guides/developer-mode Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two corrections found in self-audit: - Copilot Studio per-agent tool limit was wrong. I had 70; Microsoft Learn's add-tools-custom-agent page (updated 2026-01-29) says the orchestrator handles up to 128 with 25-30 recommended for performance. The 70 figure came from John's MVP plan and is stale. Updated mcp_overview, mcp_setup_m365_copilot, and mcp_troubleshooting. - ChatGPT setup had a "developer mode required" framing that I cited from a paraphrasing summary, not the canonical OpenAI page. The developers.openai.com docs do not gate write tools behind developer mode; standard custom connectors at Settings > Connectors > Create support write tools (with manual confirmation per call). Reverted to the actual menu path and dropped the overstated developer-mode prerequisite. Kept a one-line note that admins on Business or Enterprise plans may restrict custom connectors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copilot Studio's UI rejects an empty Client secret, but the Amperity MCP server is a PKCE public client and ignores the value (the OAuth proxy strips it). Tell the customer to fill it with a non-empty placeholder rather than leaving the field empty. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The 70 vs 128 numbers don't reconcile cleanly between Microsoft Learn and lived experience. Drop the specific cap; the customer-facing point is just that Copilot Studio limits tools and Amperity has more than the limit allows. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Same shape as the mcp_authentication page we cut earlier -- protocol walkthroughs and a discovery table that customers don't read. The endpoint URL lives in every setup page already; the OAuth values customers actually need are in mcp_setup_m365_copilot for Manual auth; DCR clients auto-discover; anyone needing the full discovery doc can curl /.well-known/oauth-authorization-server. Removes the toctree entry and the one cross-reference in mcp_overview's "Connect a client" section. Page count: 7 customer-facing pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Audited each section against amperity-mcp source code: - 401: quote actual JSON body the server returns. Drop the JWS/JWE segments hint -- the auth middleware handles both transparently via /userinfo (auth_middleware.py:137), so customers don't see this distinction. - Add: tool returned isError -- the canonical error shape returned from individual tool failures. Covers permissions, bad arguments, stale references. - "No tenant selected": quote the exact message at server.py:407-409. - Add: tenant or sandbox missing from tenant_list -- documents the tenant_resync flow for stale cache. - Write refused: separate the standard write gate from the external- send gate (campaign_schedule / orchestration_group_run), which always requires unrestricted + confirm regardless of safety mode. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Beta is small enough that speculative troubleshooting content risks documenting failure modes customers don't actually hit, while missing the ones they do. Wait for real ticket volume before reintroducing. Drops the page, the toctree entry, and the three setup-page cross- references. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
jeter-a
requested review from
a team,
Jacksonbaker323,
deab-nakussa and
jamescott
as code owners
jeter-a
changed the title
jeter-a
changed the title
Per Ben's update on the cross-stack rollout (amperity/app#67532), each prod stack now has its own MCP endpoint. The docs previously hardcoded mcp.amperity.com everywhere -- correct only for aws-prod customers. Adds a "Find your MCP URL" section to mcp_overview with the 5-row stack table, anchored at mcp-overview-stack-urls. Each setup page now begins with a note that the examples use aws-prod's URL; non-aws-prod customers substitute their stack's URL throughout. Stack URLs: - aws-prod : https://mcp.amperity.com - aws-prod-cc1 : https://mcp-aws-cc1.amperity.com - aws-prod-apse2 : https://mcp-aws-apse2.amperity.com - az-prod : https://mcp-az-prod.amperity.com - az-prod-en1 : https://mcp-az-prod-en1.amperity.com Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The *"..."* markup rendered as italics in HTML; in raw RST the asterisks looked like part of the string customers should type. Drop the emphasis, keep the quotes -- the string stands on its own as an example utterance. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Previous wording said external sends "require confirm: true regardless of safety mode" — implying confirm alone was sufficient. The actual gate in check_send_allowed (server.py:7088-7131) requires BOTH unrestricted safety mode AND confirm=true, with no sandbox exemption. Renames the section to "External send operations" and spells out: - Both gates are required on every call - Sandbox tenants do not get an exemption (unlike regular writes) - Rationale: these tools push to real-world systems beyond the tenant Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Greenninja4
reviewed
May 1, 2026
The Amperity OAuth proxy handles callback URL registration dynamically (amperity-mcp commit bc6a7f1, AI-1689). Customers do not need to copy the callback URL anywhere -- so the previous instruction was busywork that would never actually be done. Source: amperity-mcp/README.md Copilot Studio section says "the proxy handles this automatically (no Terraform update needed)". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
James caught this: slices in Amperity are database export slices (slc-xxx), not audience slices. Per server.py:6949-7034 and amperity-cli SlicesAPI: they define which tables of a database get exported to a destination via an orchestration. Moves slice_* out of "Campaigns and journeys" into a new "Data export slices" section directly above the orchestration-adjacent grouping. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- mcp_safety_modes: external-send list said `courier_group`; the actual tool is `courier_group_run`. - mcp_setup_m365_copilot Server description field: "what the is connector for" -> "what the connector is for". - mcp_setup_m365_copilot verify section: "and return details" -> "and returns details". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
jamescott
approved these changes
May 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What's here
A new MCP section under
amperity_api/source/. Six customer-facing pages and a toctree update:mcp_overviewmcp_setup_m365_copilotmcp_setup_claudemcp_setup_chatgptmcp_safety_modesmcp_tool_referenceBuilds clean under CI's
sphinx-build -W.