MCPorter

Common errors

• Error: Server "my-server-name" not found in configuration.

  cause The specified MCP server ID does not exist in any discovered configuration file (e.g., `~/.mcporter/mcporter.json`, `config/mcporter.json`, or editor imports).
  fix 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.

• Error: Auth required for server "my-oauth-server".

  cause The MCP server requires OAuth authentication, but no valid token is present or it has expired.
  fix 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.

• Error: Cannot find module 'mcporter' from ... (or similar CJS `require` error)

  cause MCPorter is primarily distributed as an ES Module, and direct `require()` calls in a CommonJS environment might fail, especially in newer Node.js versions or without proper transpilation.
  fix 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.

• Command failed: mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'
  Error: Invalid argument value for 'body': ...

  cause CLI argument parsing can be sensitive to syntax, especially with complex values, quotes, or when switching between flag-based and function-call styles.
  fix 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.

Warnings

• breaking MCPorter `v0.8.0` introduced changes to how static `Authorization` headers are handled once OAuth is active. Imported editor configurations can no longer override fresh OAuth tokens, which might break workflows relying on statically defined headers overriding dynamic tokens.
  Fix: 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.
• gotcha MCPorter `v0.9.0` added per-server exact-name tool filtering via `allowedTools` and `blockedTools` in configuration. If tools unexpectedly disappear or calls fail, verify these new filtering options in your `mcporter.json` files.
  Fix: Check your `mcporter.json` configurations for `allowedTools` or `blockedTools` arrays under server definitions. Adjust them to ensure desired tools are not unintentionally filtered out.
• breaking OAuth credentials were centralized to `~/.mcporter/credentials.json` in `v0.7.0`. Older credential caches might become invalid or require migration.
  Fix: 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.
• gotcha The CLI supports multiple call syntaxes, including colon-delimited flags (`issueId:ENG-123`) and function-call style (`linear.create_comment(issueId: "ENG-123")`). Inconsistent usage or special characters in arguments can lead to parsing errors.
  Fix: 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.
• gotcha Ad-hoc server connections via CLI flags like `--http-url` or `--stdio` are ephemeral by default. If you intend to reuse them, they must be explicitly persisted.
  Fix: 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>`.
• deprecated Legacy ad-hoc flags `--sse` and `--insecure` have been aliased to `--http-url` and `--allow-http` respectively in `v0.6.5`. While still functional, prefer the newer, more descriptive flags.
  Fix: Update scripts and documentation to use `--http-url` instead of `--sse` and `--allow-http` instead of `--insecure` for future compatibility.

Install

• npm install mcporter npm
• yarn add mcporter yarn
• pnpm add mcporter pnpm

Imports

• createRuntime
  wrong:

  const createRuntime = require('mcporter')

  correct:

  import { createRuntime } from 'mcporter'

  MCPorter is primarily an ESM module. Use ES module `import` syntax. CJS `require` is not supported for top-level entry points.
• createServerProxy
  wrong:

  import createServerProxy from 'mcporter'

  correct:

  import { createServerProxy } from 'mcporter'

  This is a named export, not a default export. Ensure you destructure it from the module.
• CallResult
  wrong:

  import { CallResult } from 'mcporter'

  correct:

  import type { CallResult } from 'mcporter'

  While `CallResult` can be imported as a value, it's primarily a type. Using `import type` is recommended for clarity and tree-shaking.
• McpServer

  import type { McpServer } from 'mcporter'

  This type represents a discovered MCP server instance. Use `import type`.

Quickstart

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.

import { createRuntime, createServerProxy } from 'mcporter';

async function main() {
  // Initialize the MCPorter runtime. It automatically discovers servers
  // from ~/.mcporter/mcporter.json, config/mcporter.json, and editor imports.
  const runtime = await createRuntime();

  // List all discovered servers and their tools.
  console.log('Discovered MCP servers and tools:');
  const servers = await runtime.listServers();
  for (const server of servers) {
    console.log(`- ${server.id}: ${server.description || 'No description'}`);
    const tools = await server.listTools();
    if (tools.length > 0) {
      console.log('  Tools:');
      for (const tool of tools) {
        console.log(`    - ${tool.name}: ${tool.description || 'No description'}`);
      }
    } else {
      console.log('  No tools found.');
    }
  }

  // Example: Interact with a specific server and tool.
  // This assumes a server named 'linear' and a tool 'create_comment' exists for demonstration.
  // Adjust server ID and tool name based on your MCPorter configuration (e.g., ~/.mcporter/mcporter.json).
  try {
    const linearServer = await runtime.getServer('linear');
    if (linearServer) {
      const linearProxy = createServerProxy(linearServer);
      // Call the tool with strongly typed arguments.
      const result = await linearProxy.createComment({
        issueId: 'ENG-123',
        body: 'Looks good from MCPorter programmatic API!',
      });
      console.log('\nResult from linear.createComment:');
      console.log(await result.markdown());
    } else {
      console.log('\nServer "linear" not found in configuration. Skipping tool call example.');
    }
  } catch (error) {
    console.error('\nError calling tool:', error);
    console.log('Ensure you have a "linear" server configured (e.g., via ~/.mcporter/mcporter.json)');
    console.log('and that the "create_comment" tool exists and is accessible.');
  }
}

main().catch(console.error);