Skip to content

Instantly share code, notes, and snippets.

@codefromthecrypt

codefromthecrypt/verification-template.md

Created March 11, 2026 08:34
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save codefromthecrypt/78f9fd5db9739e2ad4b30b33c6f3fdc7 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save codefromthecrypt/78f9fd5db9739e2ad4b30b33c6f3fdc7 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
verification-template.md

MCP Gateway Documentation Template & Verification Process

Quick Start

Replace [PROJECT_NAME], [PROJECT_URL], and [GITHUB_URL] with the actual project details, then follow the verification process below.

You are a technical documentation auditor specializing in AI infrastructure. Your task is to create a factual, evidence-based documentation section for an MCP (Model Context Protocol) gateway/platform following the strict template and verification process below.

Project to Analyze: [PROJECT_NAME]

Begin verification with these sources (use [GITHUB_URL] for code/evidence priority; [PROJECT_URL] may overlap if it's the main site/docs):

  • Website: [PROJECT_URL]
  • Primary Repository: [GITHUB_URL]

Required Template

### [project-name][projectname-main] (Company/Organization)

* **Focus:** [1-2 sentences: what it connects, how it works, key differentiator. Focus on its primary architecture type first.]

* **Launch:** ["Announcement Title"][project-launch] – <Month YYYY>, <brief summary>.

* **Current Status:** [Version: X.X.X][projectname-version] or "SaaS", Release Cadence: daily/weekly/quarterly, [GitHub Stars: X,XXX][projectname-stars]

* **Personas:** [Only from: AI Developer (X%), AI Engineer (X%), Platform Engineer (X%), Team Lead (X%)]

* **Strengths:** [4-6 verified features]
  * **[Feature]:** [Description with [evidence][projectname-featurename]]

* **Gaps:** [3-5 limitations]
  * **[Gap]:** [Description with [evidence][projectname-gapname]]

* **Example App:** [Canonical quickstart/tutorial or "None found"]

* **Routing Protocols:** [List from: OpenAI Chat Completion, OpenAI Responses, OpenAI Embeddings, MCP, ACP, A2A - with evidence]

* **MCP Catalog:** [Built-in URL | Promoted catalog URL | None]

* **Pricing:**
  * **[Tier]:** [Description, limitations, cost]

* **Verified Users:** [Up to 5 with evidence of production usage OR strategic integration]
  * **[User]:** [Usage/Integration description with [evidence][projectname-username]] (500+ star projects for OSS integrations, or notable companies for deployments/consumption)

* **Notes:** [When Open Source or Open Core, add contributor count from the owning company and notable others]
  * [~N <Org> employees][project-contributors] have authored the majority of commits; [Lead A][project-leadA] and [Lead B][project-leadB] lead development.  
    * **Microsoft:** [Contributor][project-msft] contributed <feature>.  
    * **Huawei:** [Contributor][project-huawei] contributed <feature>.  

---
[project-main]: URL
[project-launch]: URL
[project-version]: URL
[project-stars]: URL
[project-feature]: URL
[project-gap]: URL
[project-contributors]: URL
[project-leadA]: URL
[project-leadB]: URL
[project-msft]: URL
[project-huawei]: URL

Allowed Personas

Only use these four personas with >10% relevance:

  1. AI Developer - Prototypes and ships AI features
  2. AI Engineer - Deploys AI workloads for teams
  3. Platform Engineer - Abstracts AI complexity
  4. Team Lead - Makes AI tooling/budget decisions

Evidence Requirements

  1. Evidence Hierarchy (applies to all claims, including users): Code > Config > Tests > Docs > Marketing > Production configs > 500+ star OSS integrations > Official partnerships > Company API consumption > User testimonials > Technical blog posts > Marketing materials
  2. Linking: Every claim requires a link, preferring specific line numbers (e.g., file.go#L123).
  3. Checks: Search for TODOs/stubs in claimed features; verify MCP version (2024-11-05, 2025-03-26, 2025-06-18) from code, not claims; determine release cadence from history (daily/weekly/quarterly).

If you can run code:

  • Test the quickstart example
  • Verify binary/container sizes
  • Run E2E tests if available
  • Check actual performance metrics
  • Validate configuration options work

If you can search the web:

  • Search for implementation vs documentation gaps
  • Check GitHub issues for unresolved problems
  • Compare version claims vs code
  • Find user evidence in blogs/talks/repos
  • Verify transport implementations in code

User Verification Requirements:

Invalid Evidence Examples:

  • Blog posts mentioning/endorsing a product (not usage evidence)
  • Marketing materials from the project itself
  • Tutorial/educational content
  • Social media mentions without implementation proof
  • Conference talks about a product (unless showing production deployment)

Valid Evidence Hierarchy:

  1. Registry/Platform Usage Metrics: Actual usage statistics, call counts, success rates, leaderboards from the platform itself
  2. Production Config Files: Actual configuration files in company repositories showing the project in use
  3. Integration Code: Pull requests, commits, or source code showing strategic implementation (not just examples)
  4. 500+ Star OSS Projects: Must show actual dependency/integration in package.json, requirements.txt, or similar
  5. Company Engineering Blogs: Technical posts by users (not vendors) showing actual implementation challenges/solutions
  6. Public Infrastructure: Verifiable deployments, API endpoints, or services running the project

Registry/Platform Specific Evidence:

  • For registry/hosting platforms: Look for usage metrics, call counts, success rates, leaderboards
  • Monthly tool call volumes indicate production usage scale
  • Success rates above 95% suggest enterprise reliability
  • Leaderboard rankings show comparative adoption
  • Check platform-specific metrics pages (/leaderboard, /stats, /metrics)

Required Evidence Strength:

  • For companies: Must show actual deployment evidence (config files, technical blog posts by their engineers, job postings mentioning the tool in production)
  • For OSS projects: Must show direct dependency or integration code, not just mentions in README/docs
  • Avoid: Any content created by the project's own team, marketing materials, or educational/tutorial content

User Verification Checklist:

  • □ Explicit naming in implementation
  • □ Actual usage evidence
  • □ 500+ stars for OSS
  • □ Verifiable for companies
  • □ From user's materials (not project marketing)

Common Verification Points

Core Features:

  • MCP protocol version and transports (SSE, WebSocket, stdio, HTTP). Note if MCP is an optional functionality.
  • Authentication (OAuth, API keys, JWT)
  • Tool discovery and routing
  • Response streaming
  • Multi-tenancy/isolation
  • MCP catalog (built-in, promoted, or none)

Routing Protocols:

Gap Indicators:

  • TODO/FIXME comments; documentation without implementation; missing E2E tests; unverified performance claims; security in planning only; MCP outbound-only (not a gateway); preferential proprietary protocols in docs/SDKs.

Language Standards

Factual and Direct Language:

  • Use: "unimplemented" (not "limited support"); "TODO in code" (not "under development"); "stub only" (not "basic implementation"); "reports X but implements Y" for mismatches.
  • Avoid: "revolutionary", "game-changing", "cutting-edge", "best-in-class", "industry-leading", "innovative".
  • Stick to: "supports", "implements", "provides"; measurable facts (e.g., "~45MB binary", "12 contributors", "daily releases").

User Verification Language:

  • Use: "No verifiable users found" instead of assuming endorsements equal usage
  • Avoid: Conflating marketing mentions with strategic adoption
  • Require: Explicit technical implementation evidence, not promotional content

Common Verification Mistakes:

  • Ignoring platform-native usage metrics in favor of external blog searches
  • Missing registry-specific evidence when the project IS the registry
  • Conflating marketing content with usage data
  • Not checking platform leaderboards/statistics pages for concrete usage evidence

Keep Concise:

  • 1-2 line descriptions max
  • Group related links at bottom
  • Use namespaced link references: [projectname-feature] not just [feature]

Investigation Checklist

  1. Find repository: Check /examples, /docs, /test directories.
  2. Identify primary architecture: SaaS or OSS, MCP or Proprietary with MCP features.
  3. Catalog discovery: Look for built-in or promoted registries.
  4. Test features: Verify source code matches claims; run examples/E2E if possible.
  5. Document gaps: Compare claims vs implementation (e.g., via GitHub issues/searches).

Output

Provide:

  1. Completed template with evidence links
  2. Brief verification summary of major discrepancies
  3. Critical warnings for production use

Example: Open Source Project

### [agentgateway][agentgateway-main] (Solo.io)

* **Focus:** Unified routing for LLMs, agents, and MCP tools bridging providers with MCP servers and REST APIs; featuring CEL-based RBAC and xDS config in a ~45MB Rust binary.
* **Launch:** ["Solo.io Launches Agent Gateway and Introduces Agent Mesh"][agentgateway-launch] – April 2025, brings AI-native gateway with MCP routing, access controls, audit tracking, and guardrails.
* **Current Status:** [Version: v0.7.7][agentgateway-version], Release Cadence: daily, [GitHub Stars: 643][agentgateway-stars]
* **Personas:** AI Engineer (60%), AI Developer (25%), Platform Engineer (15%)
* **Strengths:**
    * **Zero Dependencies:** Single Rust binary [tested against Envoy][agentgateway-envoy-tests]
    * **RBAC & Multi-Tenancy:** [Fine-grained access control][agentgateway-mcp-authz] using CEL
    * **Flexible Configuration:** Hot reload from file or [dynamic XDS][agentgateway-config]
    * **Observability:** OTEL traces [sampled with CEL][agentgateway-telemetry-cel], [Prometheus metrics][agentgateway-metrics]
    * **OpenAPI to MCP:** [Automatic REST API exposure][agentgateway-openapi] as MCP tools
* **Gaps:**
    * **In-Memory Only:** All data [stored in memory][agentgateway-memory] without persistence
    * **Documentation Ahead:** [A2A minimal][agentgateway-a2a], [dynamic routing unimplemented][agentgateway-dynamic-todo]
    * **Version Mismatch:** Claims MCP 2025-06-18 but [implements 2025-03-26][agentgateway-mcp-version]
    * **Limited E2E Tests:** MCP tracing and dynamic discovery lack tests
* **Example App:** [@modelcontextprotocol/server-everything][agentgateway-server-everything] in [quickstart][agentgateway-quickstart]
* **Routing Protocols:** [OpenAI Chat Completion][agentgateway-chat], [OpenAI Embeddings][agentgateway-embeddings], MCP 2025-03-26
* **MCP Catalog:** None
* **Pricing:**
    * **Open Source:** [Apache 2.0][agentgateway-license], no commercial product
* **Verified Users:**
    * **kgateway:** [Static routing to SSE servers][agentgateway-kgateway]
* **Notes:**
  * [~9 Solo.io employees][agentgateway-contributors] have authored the majority of commits; [Eitan Yarmush][agentgateway-eitan] and [John Howard][agentgateway-howard] lead development.
      * **Microsoft:** [Keith Mattix II][agentgateway-keithmattix] contributed Windows support and MCP proxy features.
      * **Huawei:** [Tiger Xu][agentgateway-tigerxu] contributed infrastructure fixes.

---
[agentgateway-main]: https://github.com/agentgateway/agentgateway
[agentgateway-launch]: https://www.solo.io/press-releases/solo-io-launches-agent-gateway-and-introduces-agent-mesh
[agentgateway-version]: https://github.com/agentgateway/agentgateway/releases/tag/v0.7.7
[agentgateway-stars]: https://github.com/agentgateway/agentgateway/stargazers
[agentgateway-envoy-tests]: https://github.com/agentgateway/agentgateway/blob/main/crates/agentgateway/tests/common/compare.rs
[agentgateway-mcp-authz]: https://agentgateway.dev/docs/security/mcp-authz/
[agentgateway-config]: https://agentgateway.dev/docs/configuration/
[agentgateway-telemetry-cel]: https://github.com/agentgateway/agentgateway/blob/main/crates/agentgateway/src/telemetry/log.rs
[agentgateway-metrics]: https://agentgateway.dev/docs/observability/metrics/
[agentgateway-openapi]: https://agentgateway.dev/docs/backends/openapi/
[agentgateway-memory]: https://github.com/agentgateway/agentgateway/blob/main/crates/agentgateway/src/store/mod.rs
[agentgateway-a2a]: https://github.com/agentgateway/agentgateway/blob/main/crates/agentgateway/src/a2a/mod.rs
[agentgateway-dynamic-todo]: https://github.com/agentgateway/agentgateway/blob/main/kgateway/internal/kgateway/extensions2/plugins/backend/agentgateway/translate.go
[agentgateway-mcp-version]: https://github.com/agentgateway/agentgateway/blob/main/crates/agentgateway/src/mcp/relay/mod.rs
[agentgateway-server-everything]: https://www.npmjs.com/package/@modelcontextprotocol/server-everything
[agentgateway-quickstart]: https://agentgateway.dev/docs/quickstart/
[agentgateway-license]: https://github.com/agentgateway/agentgateway/blob/main/LICENSE
[agentgateway-kgateway]: https://kgateway.dev/docs/agentgateway/mcp/static-mcp/
[agentgateway-howard]: https://github.com/agentgateway/agentgateway/commits?author=howardjohn
[agentgateway-chat]: https://github.com/envoyproxy/ai-gateway/blob/main/site/docs/capabilities/llm-integrations/supported-endpoints.md#chat-completions
[agentgateway-embeddings]: https://github.com/envoyproxy/ai-gateway/blob/main/site/docs/capabilities/llm-integrations/supported-endpoints.md#embeddings
[agentgateway-keithmattix]: https://github.com/solo-io/agentgateway/pulls?q=is%3Apr+author%3Akeithmattix
[agentgateway-tigerxu]: https://github.com/solo-io/agentgateway/pulls?q=is%3Apr+author%3A%22Tiger+Xu%22
[agentgateway-contributors]: https://github.com/solo-io/agentgateway/graphs/contributors
[agentgateway-eitan]: https://github.com/solo-io/agentgateway/commits?author=EitanSuez
[agentgateway-howard]: https://github.com/solo-io/agentgateway/commits?author=howardjohn

Example: SaaS

### [Cloudflare AI][cloudflare-main] (Cloudflare)

* **Focus:** MCP server hosting platform on Cloudflare Workers enabling remote MCP servers with OAuth authentication; provides PaaS infrastructure for deploying MCP servers via SSE transport, not an MCP gateway for routing between servers or protocols.
* **Launch:** ["Hi Claude, build an MCP server on Cloudflare Workers"][cloudflare-launch] – December, 2024 brings MCP hosting to Cloudflare Workers, offering global scalability, built-in OAuth authentication, and seamless AI agent integration.
* **Current Status:** Review Date: 2025-08-28, [Agents SDK: v0.0.109][cloudflare-version], Release Cadence: daily, [GitHub Stars: 709][cloudflare-stars]
* **Personas:** AI Developer (50%), AI Engineer (30%), Platform Engineer (15%), Team Lead (5%)
* **Strengths:**
    * **OAuth Integration:** [Multiple OAuth providers][cloudflare-oauth] including GitHub, Google, Auth0, Stytch, Logto, Descope, and Cloudflare Access with OAuth 2.1 compliance
    * **Hibernatable WebSocket Support:** [Stateful hibernation using Durable Objects][cloudflare-hibernation] for persistent state management and cost optimization during idle periods
    * **Serverless Edge Deployment:** [Deploy MCP servers globally][cloudflare-edge] on Cloudflare Workers for low-latency execution with automatic scaling
    * **Extensive Demo Ecosystem:** [8 working examples][cloudflare-demos] including Python Workers, bearer auth, and various OAuth patterns
    * **Developer Platform Integration:** [Full Cloudflare stack access][cloudflare-platform] including AI models, D1 database, R2 storage, KV, and Durable Objects
* **Gaps:**
    * **Not an MCP Gateway:** [Hosts individual MCP servers][cloudflare-hosting-only] rather than routing between multiple servers or protocols - architecture frequently misunderstood
    * **Single Transport Support:** [Only SSE transport implemented][cloudflare-sse-only] despite WebSocket hibernation capability
    * **Outdated MCP Implementation:** [Uses @modelcontextprotocol/sdk 1.17.1][cloudflare-mcp-version] implementing MCP 2024-11-05 spec (not latest 2025-06-18)
    * **Cost Escalation Risk:** [User reports expensive bills][cloudflare-cost-warning] for high-traffic MCP servers within days of deployment, especially with Durable Objects
    * **Demo-Level Examples:** [Production readiness unclear][cloudflare-demo-focus] with [unresolved TODO markers][cloudflare-todos] in example code
* **Example App:** [remote-mcp-authless][cloudflare-authless-example] calculator with SSE transport
* **Routing Protocols:** MCP 2024-11-05 (SSE transport only)
* **MCP Catalog:** [Built-in catalog][cloudflare-catalog] for Cloudflare product APIs (Workers, R2, DNS, etc.)
* **Pricing:**
    * **Workers Free:** 100,000 requests/day, 10ms CPU per invocation
    * **Workers Paid:** $5/month + $0.30/million requests + $0.02/million CPU milliseconds
    * **Workers AI:** Free tier (10,000 neurons/day), paid tier $0.011 per 1,000 neurons
    * **Durable Objects:** Additional costs for stateful operations
* **Verified Users:**
    * **Asana:** [Demoed at Cloudflare Demo Day][cloudflare-user-asana] with 50,000+ tool calls, explicitly thanked Cloudflare team
    * **Atlassian:** [Hosted on Cloudflare infrastructure][cloudflare-user-atlassian] with quote "Cloudflare provided everything from OAuth to out-of-the-box remote MCP support"
    * **Linear:** [Deployment template shows Cloudflare][cloudflare-user-linear] in BerriAI/litellm-linear-mcp repository
    * **Stytch:** [Official partnership][cloudflare-user-stytch] for OAuth authentication in Cloudflare Workers MCP servers
* **Notes:**
    * **Architecture Clarification:** Cloudflare AI is PaaS infrastructure for hosting MCP servers on edge, not an MCP gateway for routing
    * **AI Gateway Confusion:** "AI Gateway" product handles REST API proxying (OpenAI-compatible), not MCP protocol routing capability
    * **Full Application Ownership:** Teams must build, secure, and maintain their own MCP server applications, not just configure a managed gateway

---
[cloudflare-main]: https://github.com/cloudflare/ai
[cloudflare-launch]: https://blog.cloudflare.com/model-context-protocol/
[cloudflare-version]: https://github.com/cloudflare/ai/blob/main/demos/remote-mcp-server/package.json#L17
[cloudflare-stars]: https://github.com/cloudflare/ai/stargazers
[cloudflare-oauth]: https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-github-oauth
[cloudflare-hibernation]: https://github.com/cloudflare/ai/blob/main/demos/mcp-server-bearer-auth/worker-configuration.d.ts#L449
[cloudflare-edge]: https://blog.cloudflare.com/remote-model-context-protocol-servers-mcp/
[cloudflare-demos]: https://github.com/cloudflare/ai/tree/main/demos
[cloudflare-platform]: https://developers.cloudflare.com/workers-ai/
[cloudflare-hosting-only]: https://github.com/cloudflare/ai/blob/main/demos/remote-mcp-authless/src/index.ts#L43
[cloudflare-sse-only]: https://github.com/cloudflare/ai/blob/main/demos/remote-mcp-server/src/index.ts#L24
[cloudflare-mcp-version]: https://github.com/cloudflare/ai/blob/main/package.json#L22
[cloudflare-cost-warning]: https://www.reddit.com/r/mcp/comments/1jsx438/mcp_on_cloudflare_is_too_expensive/
[cloudflare-demo-focus]: https://github.com/cloudflare/ai/blob/main/demos/remote-mcp-server/src/index.ts#L15
[cloudflare-todos]: https://github.com/cloudflare/ai/search?q=TODO
[cloudflare-authless-example]: https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-authless
[cloudflare-catalog]: https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/
[cloudflare-user-asana]: https://www.linkedin.com/posts/stuartsy_modelcontextprotocol-activity-7325338447349514240-BEPO
[cloudflare-user-atlassian]: https://www.atlassian.com/blog/announcements/remote-mcp-server
[cloudflare-user-linear]: https://github.com/BerriAI/litellm-linear-mcp
[cloudflare-user-stytch]: https://stytch.com/blog/remote-mcp-stytch-cloudflare
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment