MCP Server (Contract-only)

This page describes the shared MCP transport, auth posture, resources, and tools for g3nretailstack.

Endpoint

• MCP server: https://api.mcp.g3nretailstack.com/mcp (HTTP JSON-RPC only; CloudFront https://mcp.g3nretailstack.com/mcp redirects here).
• Protocol docs: https://mcp.g3nretailstack.com/<service>/PROTOCOL.md (mirrored to doc.g3nretailstack.com/<service>/PROTOCOL.md).
• Mirror policy: for every publish build, doc.g3nretailstack.com/<service>/PROTOCOL.md and mcp.g3nretailstack.com/<service>/PROTOCOL.md are byte-identical.
• MCP root index (https://mcp.g3nretailstack.com/) includes the publish build stamp in the same Build <build_id> • <timestamp> format used across docs surfaces.

Intended use

• This MCP server is a documentation-discovery server for AI coding assistants and agents. It is not a data-plane proxy and does not execute service API operations.
• The tools doc-read, service-index, doc-catalog, and doc-head are designed for programmatic contract exploration.
• An AI agent can use service-index to discover services, then doc-read to fetch the OpenAPI spec for a specific service before making API calls.
• Data-plane MCP tools (for example create-session or list-products) are not in scope today; this MCP server is scoped to documentation discovery only.

Auth + options

• MCP is unauthenticated today; sessions are established via MCP initialize.
• The server uses MCP session IDs (MCP-Session-Id) to correlate requests; include it on follow-up calls.
• Supported methods: POST (JSON-RPC requests) and DELETE (session close). OPTIONS is not required for server-to-server use.
• If auth is introduced in the future, it will be header-based and documented here before enforcement.

Scope

• The MCP server is doc-only: it exposes protocol/docs/OpenAPI resources and a few doc tools.
• It does not proxy or execute microservice API operations.

Streaming (SSE)

• Decision: SSE streaming is not supported on the current API Gateway + Lambda transport (JSON only).
• MCP clients that require SSE transport are not compatible with this server.
• Only JSON-RPC over HTTP POST is supported.
• Runtime Accept contract for MCP initialize/request handling currently requires clients to send Accept: application/json, text/event-stream (responses remain JSON; no SSE stream is served).
• Claude Desktop, Cursor, and similar clients that support HTTP-only MCP transport are compatible.
• If streaming is introduced, we will publish a separate SSE endpoint (e.g., ALB/Function URL) and document required headers (Accept: text/event-stream), retry/backoff, and session behavior here.

Resources

The MCP server exposes resources for:

• Per-service protocol docs (Markdown).
• Per-service OpenAPI contracts (YAML).
• Per-service surfaces/calls/playbooks/explorer pages (HTML).
• Shared Common/Story/QA doc indexes.
• All Common sidebar pages (44 pages including headers/identity, error tags, ids/codes, pagination, request context, idempotency, environments, versioning, deprecation, integration checklists, domain models, schemas, and more).
• QA pages (overview, usecases, super-usecases, tests, outcomes, playbooks).

Discover via resources/list, then fetch with resources/read.

Resource templates

The server also exposes 3 URI templates (discoverable via resources/templates/list):

Template name	URI pattern	Description
protocol-template	https://mcp.g3nretailstack.com/{service}/PROTOCOL.md	Protocol doc for any service (Markdown)
openapi-template	https://doc.g3nretailstack.com/{service}/openapi.yaml	OpenAPI contract for any service (YAML)
doc-page-template	https://doc.g3nretailstack.com/{service}/{page}/	Doc page for any service (surfaces/calls/playbooks/explorer)

Tools

Tool	Input schema	Description
doc-read	{ url: string }	Fetches a doc or OpenAPI file from the g3n doc or MCP hosts.
service-index	{}	Returns JSON with service IDs and doc/OpenAPI/explorer links.
doc-catalog	{}	Returns JSON listing common/QA pages plus per-service links.
doc-head	{ url: string }	Returns HTTP status + headers for a g3n doc/protocol URL (doc/mcp hosts only).

Session lifecycle

• Sessions are established via the MCP initialize request (POST).
• Each session receives a unique MCP-Session-Id header that must be included on follow-up calls.
• Idle TTL: sessions expire after 15 minutes of inactivity.
• Session cap: the server allows a maximum of 256 concurrent sessions; new initialize requests return 503 when the cap is reached.
• Explicit close: send a DELETE request to /mcp with the MCP-Session-Id header to close a session immediately.

Error codes

Status	Meaning	When
400	Bad request	Invalid JSON body, missing initialize request on new session
404	Not found	Unknown MCP subpath, session not found on DELETE
405	Method not allowed	GET /mcp (SSE not available), unsupported HTTP method
406	Not acceptable	Accept header does not include text/event-stream (runtime contract)
410	Gone	Legacy subpath (use POST /mcp with MCP Streamable HTTP)
500	Internal error	Unexpected handler error
503	Service unavailable	Session limit reached (256 concurrent sessions)

Initialize example

PROTOCOL=2025-03-26
curl -i -X POST https://api.mcp.g3nretailstack.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":"init","method":"initialize","params":{"protocolVersion":"'"$PROTOCOL"'","clientInfo":{"name":"manual","version":"0.0.1"},"capabilities":{"resources":{},"logging":{}}}}'