MCPorter is a TypeScript runtime and CLI tool designed to facilitate interaction with Model Context Protocol (MCP) servers. It provides capabilities for zero-configuration discovery of MCP servers across various environments (local files, editors like Cursor/Claude/VS Code), one-command CLI generation for any server definition, and the creation of strongly typed tool clients. The library offers a composable API for programmatic access, handling aspects like OAuth caching, log tailing, and different transport mechanisms (HTTP, SSE, stdio). Currently at version `0.9.0`, MCPorter maintains a rapid release cadence, indicated by frequent minor and patch updates, continuously enhancing its functionality for 'code execution' workflows as envisioned by the Model Context Protocol. Its key differentiators include automated config merging, ergonomic API wrappers that apply JSON-schema defaults and validation, and robust support for ad-hoc and OAuth-backed connections.
npm install mcporterVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to programmatically discover MCP servers and tools, and invoke a tool using the `createRuntime` and `createServerProxy` APIs. It lists all configured servers and then attempts to call a hypothetical `linear.createComment` tool, handling potential configuration issues.
Review configurations where static `Authorization` headers are present. For OAuth-backed servers, ensure token management is handled through MCPorter's OAuth flows or explicitly clear cached tokens if issues arise.
Check your `mcporter.json` configurations for `allowedTools` or `blockedTools` arrays under server definitions. Adjust them to ensure desired tools are not unintentionally filtered out.
If experiencing OAuth issues after upgrading, use `mcporter auth --reset` to clear corrupted caches and re-authenticate. MCPorter should attempt auto-migration, but manual reset can resolve stubborn issues.
For complex arguments or those containing spaces/special characters, prefer the function-call style with proper quoting, or use `--args '{"key":"value"}'` for JSON payloads. Refer to `mcporter call --help` or `docs/call-syntax.md` for details.To persist an ad-hoc server definition, add `--persist <path/to/config.json>` to your `mcporter list` or `mcporter config add` command. For OAuth with ad-hoc servers, use `mcporter auth <url>` or `mcporter config login <url>`.
Update scripts and documentation to use `--http-url` instead of `--sse` and `--allow-http` instead of `--insecure` for future compatibility.
Verify the server ID is correct. Run `npx mcporter list` to see available servers. If the server is external or ad-hoc, ensure it's properly added using `mcporter config add` or specified via ad-hoc CLI flags.
Run `npx mcporter auth my-oauth-server` to initiate the OAuth flow in your browser. If issues persist, try `npx mcporter auth my-oauth-server --reset` to clear existing credentials.
Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) and use `import { ... } from 'mcporter';` syntax. If you must use CommonJS, consider dynamic `import('mcporter')` or a build step to transpile.Review the specific error message for argument type/format mismatch. Ensure proper quoting for string values, especially those with spaces. Consider using the function-call syntax with explicit string literals or `--args` for JSON objects. Run `mcporter list <server> --schema` for expected argument types.