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.

Related MCP server: Onto MCP Server

Deployment modes

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.

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

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