docs(agentic): document get_pg_capabilities MCP tool (#135253)

[gergesfikry-ottu]

What & why

Documents the newly shipped get_pg_capabilities tool on the Ottu Core MCP server, which powers Agentic merchant onboarding — an agent uses it to discover which payment gateways and banks are available per country before configuring a merchant.

Ottu ticket: #135253.

This is an MCP tool, not a REST endpoint, so it is documented in a new "MCP Tools" developer section rather than under the auto-generated docs/developers/apis/* OpenAPI pages.

Pages added

Page	Contents
developers/mcp-tools/index.mdx	Ottu Core MCP server overview — Streamable HTTP /mcp/ connection, Bearer auth, per-tool permission model, and the shared { "error": ... } result envelope.
developers/mcp-tools/pg-capabilities.mdx	Full get_pg_capabilities reference — permission, parameters, the three progressive-disclosure modes with real request/response examples, response schema (gateway profile / provider / wallet), enum reference tables, and error responses.

Also adds a Pattern-B "MCP Tools" category to developerSidebar in sidebars.ts (Overview + PG Capabilities), placed before Reference.

Faithful to source

Every example payload is taken verbatim from the core_backend tests (tests/test_contrib/test_mcp/test_mcp.py), so the docs match the tool's real output rather than a simplified spec. In particular:

• Gateway and wallet name fields are bilingual objects ({ "en": …, "ar": … }), e.g. MPGS renders as Credit/Debit Card — not the raw code.
• The supported-country order is the catalogue order: kw, ksa, om, bh, uae.
• Permission gate is gateway.view_pgmid; error messages match the service exactly.
• The write counterpart create_pg_config is intentionally not documented (held for #137821).

Human display names are used in prose (Apple Pay, National Bank of Kuwait); raw codes appear in the schema/enum tables. No internal implementation, credentials, or code is exposed.

Verification

• npm run typecheck — passes.
• npm run build — passes; the two new pages add no broken links or anchors (remaining build warnings are pre-existing on other pages).
• Rendered locally via npm run serve + Playwright: overview and tool pages render correctly, the Mermaid workflow diagram renders with the correct single-accent styling, code blocks are syntax-highlighted, and the sidebar/anchor navigation works.

Base branch

Branched from dev and targets dev (the repo's integration branch → staging). Retarget to main if production-direct is preferred.

Please review — do not merge yet.

[gergesfikry-ottu]

@claude do code review

[claude]

Claude finished @gergesfikry-ottu's task in 3m 2s —— View job

---

Code Review

• Gather context (diff, changed files)
• Review docs/developers/mcp-tools/index.mdx
• Review docs/developers/mcp-tools/pg-capabilities.mdx
• Review sidebars.ts changes
• Check against CLAUDE.md doc standards
• Post final review

Nice addition — first documented MCP tool, and it's thorough. I verified every in-page anchor (#mode-1, #response-reference, #gateway-codes, #wallet-object, etc.) resolves to a real heading, cross-file links (/developers/mcp-tools/#connecting, /developers/payments/payment-methods, etc.) point at real docs, the mermaid block matches the repo's standard theme init exactly, and the base-URL code sample correctly uses OTTU_CONNECT_BASE_URL + <CodeBlock> per the root CLAUDE.md rule. Sidebar uses Pattern B (type: 'doc', one page per file) which is the right call for two substantial pages, consistent with checkout-sdk.

Note: I could not run npm run typecheck / npm run build in this sandboxed environment (command approval unavailable) — worth confirming those pass, especially since sidebars.ts id fields must match the doc front matter exactly.

One correctness/consistency issue and a couple of structural notes against docs/developers/CLAUDE.md:

1. docs/developers/mcp-tools/index.mdx:28-40 — standalone ## Authentication and ## Permissions H2 sections
docs/developers/CLAUDE.md explicitly says: "No standalone Authentication or Permissions sections — authentication is documented in getting-started/authentication.md." This page adds full ## Authentication and ## Permissions sections instead of just linking out.
That said, this may be a deliberate (and reasonable) exception: getting-started/authentication.md currently documents Basic Auth, API-Key, and Public Key — it never mentions Bearer token auth, which is what the MCP server actually requires. So this section isn't strictly duplicative today; it's filling a real gap. Two ways to resolve, your call:

• Add "Bearer Token" as a fourth method in getting-started/authentication.md and shrink this section to a link + one-liner (matches the rule as written), or
• Keep it inline here (since MCP auth is genuinely distinct) but note explicitly it's a new mechanism not covered on the authentication page, so a future reader of authentication.md doesn't miss it.
  Fix this →

2. docs/developers/mcp-tools/pg-capabilities.mdx — page structure diverges from the fixed template
The mandated section order is Overview → When to Use → Setup → Guide → API Reference → Best Practices → FAQ → What's Next?. This page instead has Overview → When to Use → Guide → Parameters → Usage modes → Response reference → Enum reference → Errors → FAQ → What's Next? — there's no ## API Reference H2 at all, and Parameters/Usage modes/Response reference/Enum reference/Errors aren't in the canonical list. This is understandable since there's no OpenAPI spec to embed via <ApiDocEmbed> for an MCP tool, and checkout-sdk/web.mdx shows precedent for reference-heavy pages departing from the feature-page template. Still, consider wrapping Parameters / Usage modes / Response reference / Enum reference / Errors under a single ## API Reference H2 (as H3s) so the page satisfies "API Reference always has an H2 heading" and stays scannable/consistent with other pages for readers jumping via TOC.

3. docs/developers/mcp-tools/pg-capabilities.mdx:36,53 — Guide subsections don't use the canonical names
CLAUDE.md specifies canonical ### subsections under Guide: Workflow, Live Demo, Step-by-Step, Use Cases. This page uses ### How it fits and ### Calling the tool instead. Minor/nit — the content itself is fine (mermaid flow + a walkthrough), but renaming to ### Workflow and ### Step-by-Step would match the convention other guide pages use.

Everything else — permission-gated error handling, the progressive-disclosure "3 modes" structure, the BNPL <details> example, the enum reference tables, and the FAQ (correctly using the <FAQ>/<FAQItem> component, matching invoices.mdx) — is well done and self-contained per the doc philosophy.
· Branch: task/135253-pg-capabilities-docs