Skip to main content

MAD MCP Portal

The Portal is the agent-facing control plane for the provider fleet. Agent Contract v2 keeps the default surface to 12 tools, returns lossless references on demand, and separates read, write, and destructive execution.

Authentication​

  • Header: Authorization

  • Format: Bearer mad_live_***

  • New clients default to the agent_core profile. Existing private clients retain their assigned legacy profile until migrated.

  • Never pass a Portal grant, provider credential, or OAuth token as a tool argument.

  • Write and destructive execution require a matching unexpired preview token; destructive tools also require the manifest-defined confirmation phrase.

Catalog Coverage​

  • Raw provider tools: 12
  • Exposed compatibility tools: 12
  • Agent-ready tools: 12
  • Documented descriptors: 12
  • Public reference pages: 12
  • Source repository: https://github.com/MADPANDA3D/main-site
  • Catalog version: portal-agent-contract-v2-2026.07.12.1
  • Catalog verified: 2026-07-12T21:09:19.552817+00:00 (5 days old)
  • Guide verified: 2026-07-12T00:00:00.000Z (6 days old)
  • Committed snapshot: catalog-5ec40de147b11c40
  • Docs generated: 2026-07-18T00:19:58.776Z

Best For​

  • Discovering the right provider tool without loading the full fleet catalog.
  • Validating configuration, profile selection, schemas, risk, and confirmation before provider execution.
  • Reporting semantic or transport failures with a trace ID and secret-safe context.
  • Reading current support tickets and published platform releases.

Agent Workflow​

  • Call portal.welcome once when the client or workflow is unfamiliar.
  • Use portal.list_services to check availability, then portal.find_tools with a short multi-token task phrase.
  • Fetch the complete descriptor with portal.get_tool_reference before constructing arguments.
  • Call portal.preview_tool_call for writes or destructive operations; do not change arguments after preview.
  • Use the risk-matched executor. Treat outcome_unknown as a stop condition and inspect state before any retry.
  • Call portal.report_bug when a tool returns a semantic failure or an unexpected transport result.

Operating Notes​

  • Default discovery includes agent_ready tools only and returns at most 25 matches.
  • Default results are bounded; follow pagination or resource links instead of requesting hollow schemas or oversized payloads.
  • Preview tokens expire after 10 minutes, bind to the argument hash and caller, and are single-use for writes.
  • The advanced_broker pack retains portal.list_service_tools and portal.call_service_tool for compatible legacy automations.

Transport Profiles​

  • agent_core: the 12-tool default for new internal clients.
  • knowledge, projects, operator, and site_owner: optional focused packs.
  • advanced_broker: lossless paginated provider catalog and legacy broker helpers.
  • legacy_private: compatibility profile for existing OAuth clients and master keys during staged migration.

Read-only Tools​

  • Call Read Tool — Execute one catalog-declared read-only tool.
  • Check Connection — Check broker authentication and catalog readiness without provider work.
  • Find Tools — Rank agent-ready catalog tools for a natural-language intent.
  • Get Tool Reference — Return one lossless descriptor with schemas, safety rules, and hash.
  • List Releases — List MAD MCP releases, affected services, and tools.
  • List Services — List configured services visible to this client.
  • List Tickets — List visible support tickets with filters and pagination.
  • Preview Tool Call — Validate configuration, schema, risk, and confirmation; sign a 10-minute write token.
  • Welcome — Explain MAD MCP discovery, safe execution, and bug reporting.

Write and Destructive Tools​

  • Call Destructive Tool — Execute one destructive tool with its token and exact confirmation phrase.
  • Call Write Tool — Execute one non-destructive write with its matching preview token.
  • Report Bug — Create a support ticket for a failed tool call.