MCP Development Specification

Overview

This document defines the technical requirements for listing an MCP service on JellyHub. All MCPs proxied through the JellyHub Gateway must meet these standards.

Protocol Requirements

• Must implement MCP Specification 2025-03-26 or later.
• Must support Streamable HTTP transport (legacy HTTP+SSE is not accepted).
• Must implement standard JSON-RPC 2.0 communication (tools/list, tools/call, etc.).

Legacy SSE-only MCPs cannot be listed. The MCP SDK upgrade cost is minimal — creators should migrate to Streamable HTTP.

Endpoint Requirements

• Provide a publicly accessible HTTPS endpoint as the upstream URL.
• The endpoint must accept POST requests with Content-Type: application/json.
• If authentication is required, provide a static API Key or Bearer Token. JellyHub stores it encrypted and injects it into proxied request headers.

Listing Process

1. Creator submits MCP information (name, description, upstream URL, auth method).
2. JellyHub admin enters the MCP in the admin backend, configuring upstream_url and upstream_headers.
3. Admin runs a connectivity test (automatic tools/list call to verify protocol compatibility).
4. Once verified, admin configures pricing model and free quota policy.
5. After enabling, the MCP becomes visible on the marketplace and the proxy URL is active.

Gateway URL format: https://hub.seajelly.ai/api/mcp/{slug}

What Creators Get

• A JellyHub proxy URL for promotion — all traffic is routed through JellyHub, so creators don't need to build their own rate limiting or billing.
• The admin backend shows per-MCP stats: total calls, active users, error rates.

Gateway Behavior

The JellyHub Gateway acts as a double information barrier:

• Users don't know the upstream MCP's real address or credentials.
• Upstream MCPs don't know which user is calling — the Gateway replaces auth headers.

Request flow:

1. User sends POST to /api/mcp/{slug} with Authorization: Bearer jh_live_xxx
2. Gateway validates API Key, checks rate limit, deducts quota
3. Gateway replaces headers with upstream credentials
4. Gateway forwards POST to upstream_url
5. Response returned to user with X-JellyHub-Quota-Remaining header

JSON-RPC Error Codes

If the Gateway rejects a request, it returns a standard JSON-RPC 2.0 error:

Security Notes

• Upstream URLs are validated against SSRF patterns before saving.
• Upstream credentials (upstream_headers) are encrypted at rest.
• JellyHub API Keys use a jh_live_ prefix with SHA-256 hashing for storage.