mastra-ai/mastra · error · Error

Server configuration must include either a command or a url.

Error message

Server configuration must include either a command or a url.

What it means

InternalMastraMCPClient's connection initialization requires exactly one transport: a stdio command or an HTTP url. If the resolved server configuration contains neither (and no pre-connected transport), the constructor/init path throws this error instead of attempting a connect. It is a configuration-shape guard.

Source

Thrown at packages/mcp/src/client/client.ts:835

  async connect() {
    if (this.isConnected) {
      return this.isConnected;
    }

    this.isConnected = new Promise<boolean>(async (resolve, reject) => {
      try {
        // A previous failed connect attempt can leave a stale transport attached
        // to the SDK client; release it or every reconnect fails (issue #19862).
        await this.detachStaleClientTransport();

        const { command, url } = this.serverConfig;

        if (command) {
          await this.connectStdio(command);
        } else if (url) {
          await this.connectHttp(url);
        } else {
          throw new Error('Server configuration must include either a command or a url.');
        }

        this.refreshServerInstructions();

        resolve(true);

        // Scope the reset to this connection so an older handler retained across
        // reconnects cannot clear the state of a replacement connection.
        const connectedTransport = this.transport;
        const connectionPromise = this.isConnected;
        if (this.client.onclose !== this.clientConnectionOnClose) {
          this.clientBaseOnClose = this.client.onclose;
        }
        const connectionOnClose = () => {
          if (this.transport === connectedTransport) {
            this.log('debug', `MCP server connection closed`);
            // Close the stale transport before any reconnect so its EventSource/session
            // can't keep retrying and leak server-side sessions (issue #16693). Clear

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add the required connection field to the server config: either `command` (stdio) or `url` (HTTP)
2. Validate the server config object before constructing the client
3. Check the env/config source actually resolves (typos, missing env vars)
4. Remove empty/dead server entries from the config

Example fix

// before
const client = new InternalMastraMCPClient({ name: 'weather' });
// after
const client = new InternalMastraMCPClient({ name: 'weather', url: process.env.WEATHER_MCP_URL });

function validateServerConfig(cfg: { command?: string; url?: string }) {
  if (!cfg.command && !cfg.url) {
    throw new Error('Server config needs either command (stdio) or url (HTTP)');
  }
}
validateServerConfig(serverConfig);

function hasTransport(cfg: { command?: string; url?: string }): boolean {
  return typeof cfg.command === 'string' || typeof cfg.url === 'string';
}

try {
  const client = new InternalMastraMCPClient(config);
  await client.connect();
} catch (e) {
  if (e instanceof Error && e.message.includes('must include either a command or a url')) {
    logger.error(`Malformed MCP server config for '${config.name}': set command or url`);
  }
  throw e;
}

When it happens

Trigger: Constructing the client or registering a server whose config object omits both `command` and `url` — e.g. an empty config file entry, environment-driven config where the env var backing the url/command is unset, or a typo'd config key.

Common situations: MCP config JSON/YAML entry missing the url field; process.env value undefined so neither branch is taken; renaming keys in a config file; loading config where the server entry is `{ name: 'x' }` only.

Related errors

• Cookie password must be at least 32 characters. Set WORKOS_C
• MastraClient.deleteThread() requires exactly one of agentId
• runId is required to stream an agent builder action
• Factory rule version is required.
• ${label} must be an object.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/cbd3a65e5cca08c5. Report an issue: GitHub.