@mcpcloud/runtime

The runtime for MCP servers generated by MCPCloud. Generated bundles are data + handlers; this package provides the behavior: transports, configuration, upstream auth (API key + delegated OAuth with URL elicitation), request building, input validation, response projection, and wrapper-mode tool discovery.

Usage (generated code)

import { defineServer, toWorkerHandler } from '@mcpcloud/runtime'

import { searchReposDefinition } from './tools/search-repos.definition'
import { executeSearchRepos } from './tools/search-repos'

const server = defineServer({
  identity: {
    serverName: 'GitHub MCP',
    serverVersion: '1.0.0',
    defaultUpstreamBaseUrl: 'https://api.github.com',
    apiKeyHeader: 'Authorization',
    apiKeyPrefix: 'Bearer ',
  },
  discoveryMode: 'all',
  tools: [{ definition: searchReposDefinition, handler: executeSearchRepos }],
})

export default toWorkerHandler(server) // Cloudflare Workers

Other entries:

• @mcpcloud/runtime/stdio — startStdioServer(server) for local MCP clients.
• @mcpcloud/runtime/node — serve(server, { port }) for self-hosted / container deployments (/health + /mcp included).

Configuration

All runtime configuration is environment-driven (UPSTREAM_*, MCP_OAUTH_*, MCP_RUNTIME_AUTH_*). See the .env.example shipped with your exported server for the bindings your server requires. The MCP_OAUTH_RUNTIME_TOKEN platform credential is module-private by design and never appears on the public RuntimeConfig.

Versioning

Semver. The public API is everything exported from the three entries; minified internals are not API. Deployed and exported servers pin exact versions.

License

Proprietary. Use with MCPCloud-generated servers (including self-hosted) is permitted; redistribution and competing use are not. Full text:

MCPCloud Runtime License

Copyright (c) 2026 MCPCloud.sh. All rights reserved.

Permission is granted to use this package, in unmodified form, as the runtime dependency of MCP servers generated by the MCPCloud platform — including running such servers on MCPCloud-managed infrastructure, locally, or on infrastructure you operate yourself.

The following are NOT permitted without prior written consent from MCPCloud:

1. Redistributing this package, or modified versions of it, other than as the unmodified dependency of an MCPCloud-generated server.
2. Using this package, in whole or in part, to build, operate, or improve a product or service that competes with MCPCloud, including MCP server generation, hosting, or distribution platforms.
3. Removing or altering this license, the copyright notice, or any embedded attribution.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The same text ships as LICENSE inside the package.