MEGA MCP Server

Independent Model Context Protocol server for MEGA Hub. One shared tool core runs as a Cloudflare Worker, a local stdio process, a local Streamable HTTP server, or an unprivileged Docker container.

Capabilities

• Typed model, dataset, Space, repository, and paper search and details.
• Repository inspection with README, file tree, refs, and recent commits.
• Filesystem-style list, read, stat, write, and delete operations.
• Space source context, deployment status, build/run logs, pause, and restart.
• One-shot and scheduled Jobs: list, inspect, logs, run, cancel, create, suspend, resume, trigger, and delete.
• Live MEGA OpenAPI search and operation retrieval.
• User, paper, model, dataset, and repository-context prompts.
• OAuth 2.0 Protected Resource Metadata with scope-aware challenges.
• Exact tool allowlists, reusable bouquets, and per-connection Space bounds.

HF-specific Gradio invocation is represented by MEGA Space runtime controls. Interactive HF Sandbox operations are represented by isolated MEGA Jobs; the server does not advertise endpoints the MEGA platform does not implement.

Deployment modes

Mode	Entry point	Intended use
Cloudflare Worker	src/worker.ts	Hosted Streamable HTTP service
Local stdio	mega-mcp-server	Desktop agents and CLIs
Local HTTP	mega-mcp-server-http	Development or self-hosting
Container	Dockerfile	Portable stateless HTTP deployment

The MCP service owns transport, validation, tool selection, result shaping, and Hub API calls. MEGA Hub remains the policy and data owner. Every operation forwards the caller's token to Hub, which enforces token scopes, repository membership, organization policy, resource groups, network rules, and billing.

No Durable Object is required: the Streamable HTTP implementation uses stateless JSON responses and creates one MCP server per request.

Local stdio

Requires Node.js 22 or newer.

npm ci
npm run build
MEGA_API_BASE_URL=https://hub.example.com \
DEFAULT_MEGA_TOKEN=mega_xxx \
node dist/stdio.js

Client configuration from a checkout:

{
  "mcpServers": {
    "mega": {
      "command": "node",
      "args": ["/absolute/path/to/mega-mcp-server/dist/stdio.js"],
      "env": {
        "MEGA_API_BASE_URL": "${MEGA_API_BASE_URL}",
        "DEFAULT_MEGA_TOKEN": "${MEGA_TOKEN}"
      }
    }
  }
}

Published-package usage:

MEGA_API_BASE_URL=https://hub.example.com \
DEFAULT_MEGA_TOKEN=mega_xxx \
npx -y @tensorplay/mega-mcp-server

Local HTTP

npm ci
npm run build
MEGA_API_BASE_URL=https://hub.example.com npm start

The default endpoint is http://127.0.0.1:3000/mcp; health checks use /healthz, and protected resource metadata is available at /.well-known/oauth-protected-resource/mcp.

codex mcp add mega-local \
  --url http://127.0.0.1:3000/mcp \
  --bearer-token-env-var MEGA_TOKEN

Local HTTP accepts the request Authorization header. DEFAULT_MEGA_TOKEN is only a development fallback and must not be configured on a shared server.

Docker

docker build -t mega-mcp-server .
docker run --rm -p 3000:3000 \
  -e MEGA_API_BASE_URL=https://hub.example.com \
  mega-mcp-server

The runtime image is unprivileged, contains production dependencies only, and has a /healthz health check.

Tool selection

Safe read tools are enabled by default. Repository writes, file deletion, Space controls, and all Job operations require explicit connection settings, even when the token has the corresponding scope.

/mcp?tools=mega_get_repository,mega_list_files
/mcp?bouquet=all
/mcp?bouquet=read&mix=jobs-read
/mcp?bouquet=search&mix=docs,files
/mcp?spaces=team/orbit,team/evaluator

tools= is an exact allowlist and takes precedence over bouquets.

Bouquet	Contents
read	All safe identity, search, detail, docs, paper, file, and Space reads
search	Repository, model, dataset, Space, paper, and docs search
spaces	Space search, source context, runtime, and logs
dynamic_space	MEGA Space runtime and explicit controls
docs	OpenAPI search and operation details
files	File, commit, and ref reads
research	Paper search and details
repositories	Safe reads plus repository and file writes
write	Repository/file writes and Space controls
jobs-read	Job list, details, and logs
jobs	All one-shot and scheduled Job operations
sandbox	Isolated MEGA Jobs interface
hf_api, proxy	Safe MEGA API surface for preset compatibility
all	Every built-in tool

For stdio, use MEGA_MCP_TOOLS, MEGA_MCP_BOUQUET, MEGA_MCP_MIX, and MEGA_MCP_SPACES. At most 20 Spaces can be pinned to one connection.

Tool groups

Identity and discovery:

• mega_whoami
• mega_search_models, mega_get_model
• mega_search_datasets, mega_get_dataset
• mega_search_spaces, mega_get_space, mega_get_space_runtime
• mega_search_repositories, mega_get_repository, mega_inspect_repository
• mega_search_papers, mega_get_paper
• mega_search_docs, mega_get_doc

Files and revisions:

• mega_list_files, mega_get_file, mega_list_commits, mega_list_refs
• mega_fs
• mega_put_file, mega_delete_file

Repository and Space writes:

• mega_create_repository, mega_duplicate_repository
• mega_manage_space

Jobs:

• mega_list_jobs, mega_get_job, mega_get_job_logs
• mega_create_job, mega_cancel_job
• mega_jobs for one-shot and scheduled operations

mega_fs, repository writes, Space controls, and Jobs are not enabled by default. Tool selection is not authorization; Hub scope checks always apply.

Prompts and resources

Prompts:

• mega_user_summary
• mega_paper_summary
• mega_model_details
• mega_dataset_details
• mega_repository_context

Resources:

• mega://server/guide
• mega://docs/openapi

OAuth discovery

The HTTP transports implement the MCP authorization discovery chain:

1. An unauthenticated MCP request returns 401 with resource_metadata.
2. The protected-resource document identifies the configured Hub authorization server and supported scopes.
3. The Hub authorization server publishes OAuth/OIDC discovery metadata.
4. OAuth-capable clients can use authorization code with PKCE; direct bearer tokens remain supported for local clients and automation.

Configuration

Variable	Default	Applies to	Purpose
MEGA_API_BASE_URL	required	All	MEGA Hub API origin
MEGA_API_TIMEOUT_MS	12500	All	Per-request Hub timeout
MCP_PUBLIC_URL	Request origin	Worker	Canonical protected-resource URL
DEFAULT_MEGA_TOKEN	unset	Local only	stdio token or local HTTP fallback
HOST	0.0.0.0	Local HTTP	Listen address
PORT	3000	Local HTTP	Listen port

Only HTTPS Hub origins are accepted outside localhost development.

Worker deployment

wrangler.jsonc is a public, provider-neutral template with example origins and no routes, service names, datasets, account identifiers, or production topology. Supply environment-specific bindings and routes in a separate, untracked Wrangler configuration.

npm ci
npm run check
npx wrangler deploy --config /path/to/private-wrangler.jsonc

The optional HUB fetch binding avoids a public network hop. The optional METRICS Analytics Engine binding records method, tool, status, duration, and count only; tokens, arguments, file contents, and results are never recorded.

Development

npm ci
npm run typecheck
npm test
npm run build
npm run deploy:dry-run
npm pack --dry-run

Tests cover the shared MCP protocol, Hub request mapping, local HTTP, stdio selection, and the Worker in the workerd-based Vitest pool.

Security reports follow SECURITY.md. Contribution and release expectations are in CONTRIBUTING.md.

License

MIT