nanocoai/nanoclaw · error · Error

type "http" requires url

Error message

type "http" requires url

What it means

Thrown by parseMcpServerConfig when type is "http" (or "streamable-http") but no `url` is provided. HTTP-transport MCP servers are addressed by endpoint URL, so it is required and validated eagerly.

Source

Thrown at src/container-config.ts:139

 * Parse one CLI or approval payload into the persisted MCP config shape.
 * Duplicated in container/agent-runner/src/mcp-tools/self-mod.ts
 * (parseMcpServerInput) — no shared modules across the host/container
 * boundary; keep the two in sync.
 */
export function parseMcpServerConfig(input: Record<string, unknown>): McpServerConfig {
  const command = typeof input.command === 'string' && input.command.trim() ? input.command : undefined;
  const url = typeof input.url === 'string' && input.url.trim() ? input.url.trim() : undefined;

  // A declared transport is honored; absence keeps the legacy CLI inference
  // (url → http, command → stdio). "streamable-http" is the Agent Plugins
  // spelling of the internal "http".
  const type = input.type === 'streamable-http' ? 'http' : input.type;
  if (type === 'sse') throw new Error('unsupported transport "sse"');
  if (type !== undefined && type !== 'stdio' && type !== 'http') {
    throw new Error('type must be "stdio", "http", or "streamable-http"');
  }
  if (type === 'stdio' && !command) throw new Error('type "stdio" requires command');
  if (type === 'http' && !url) throw new Error('type "http" requires url');

  const instructions = input.instructions;
  if (instructions !== undefined && typeof instructions !== 'string') {
    throw new Error('MCP instructions must be a string');
  }

  if (url !== undefined) {
    if (command !== undefined) throw new Error('Provide exactly one of command or url');
    if (input.args !== undefined || input.env !== undefined || input.cwd !== undefined) {
      throw new Error('args, env, and cwd are only valid with command');
    }
    let parsed: URL;
    try {
      parsed = new URL(url);
    } catch (err) {
      throw new Error('url must be a valid HTTP(S) URL', { cause: err });
    }
    const loopback = ['localhost', '127.0.0.1', '[::1]', 'host.docker.internal'].includes(parsed.hostname);

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Add the `url` field, e.g. {"type":"http","url":"https://mcp.example.com/mcp"}
2. If the server is local, use command-based stdio transport instead
3. Check for misspellings of the url key in the JSON payload

Example fix

// before
{"type":"http","headers":{"x":"y"}}
// after
{"type":"http","url":"https://mcp.example.com/mcp"}

if ((srv.type === 'http' || srv.type === 'streamable-http') && !srv.url) throw new UserError('http MCP entry needs url');

function isValidHttpEntry(e: any): e is {type:'http'; url:string} {
  return (e?.type === 'http' || e?.type === 'streamable-http') && typeof e.url === 'string';
}

catch (err) { if (err.message.includes('requires url')) promptForUrl(); else throw err; }

When it happens

Trigger: Configuring an MCP server entry with type http/streamable-http and only a command, or with neither command nor url; applies to ncl add-mcp-server, the self-mod tool, and direct parseMcpServerConfig calls.

Common situations: Converting a stdio entry to http but leaving `command` in place; typo like "uri" instead of "url"; expecting the SDK to derive the URL from a name.

Related errors

• type "stdio" requires command
• server name must be 1-64 characters of letters, digits, "_"
• unsupported transport "sse"
• type must be "stdio", "http", or "streamable-http"
• MCP instructions must be a string

AI-assisted analysis of nanocoai/nanoclaw@294ef2aee8 (2026-08-28). Data as JSON: /api/errors/e16fba33b590ab70. Report an issue: GitHub.