Feature Request: Support HTTP Authorization headers for direct CLI usage

[g-click-trade]

🤖 Written by Claude Code

---

Summary

Add support for passing HTTP Authorization headers when using mcptools CLI commands (tools, call, shell) with HTTP/SSE MCP servers that require authentication.

Use Case

Many MCP servers (like Linear's MCP server) require Bearer token authentication. Currently, there's no way to pass these headers when using mcptools directly from the command line.

Example scenario:

# This should work but doesn't - no way to pass auth headers
mcptools tools https://mcp.linear.app/mcp --headers "Authorization=Bearer <token>"

What Was Tried

Attempt 1: Direct URL with --headers flag

mcptools tools https://mcp.linear.app/mcp --headers "Authorization=Bearer <token>"

Result: --headers flag is not recognized for tools command.

Attempt 2: Adding headers to aliases.json

mcptools alias add linear https://mcp.linear.app/mcp

Then manually edited ~/.mcpt/aliases.json:

{
  "linear": {
    "command": "https://mcp.linear.app/mcp",
    "headers": {
      "Authorization": "Bearer <token>"
    }
  }
}

mcptools tools linear

Result: 401 Unauthorized - the headers field in aliases.json is not being read/sent.

Attempt 3: Environment variable

MCP_HTTP_HEADERS="Authorization=Bearer <token>" mcptools tools https://mcp.linear.app/mcp

Result: 401 Unauthorized - environment variable not recognized.

Attempt 4: Using configs set (partial success)

mcptools configs set mcp-linear linear https://mcp.linear.app/mcp \
  --config ~/.mcpt/mcp-config.json \
  --headers "Authorization=Bearer <token>"

Result: Successfully stores the config with headers visible in configs view:

mcp-linear
  linear (sse):
    https://mcp.linear.app/mcp
      Authorization: Bearer <token>

BUT there's no way to use this config with tools/call/shell commands:

mcptools tools mcp-linear:linear
# Error: executable file not found in $PATH

Analysis

The configs subsystem appears designed for managing IDE config files (Cursor, VSCode, Windsurf), not for direct mcptools CLI usage. The HTTP transport code auto-detects URLs but has no mechanism to accept custom headers.

Suggested Solutions

Option A: Add --headers flag to relevant commands

mcptools tools https://mcp.linear.app/mcp --headers "Authorization=Bearer <token>"
mcptools call https://mcp.linear.app/mcp list_issues --headers "Authorization=Bearer <token>"
mcptools shell https://mcp.linear.app/mcp --headers "Authorization=Bearer <token>"

Option B: Support headers in aliases.json

Make the alias system read and use the headers field for HTTP URLs:

{
  "linear": {
    "command": "https://mcp.linear.app/mcp",
    "headers": {
      "Authorization": "Bearer <token>"
    }
  }
}

Then mcptools tools linear would send those headers.

Option C: Environment variable support

MCP_HTTP_HEADERS="Authorization=Bearer <token>" mcptools tools https://mcp.linear.app/mcp
# or
MCP_AUTH_TOKEN="<token>" mcptools tools https://mcp.linear.app/mcp

Option D: Use configs for direct CLI usage

Allow referencing servers from config aliases:

mcptools tools --config mcp-linear --server linear
# or
mcptools tools @mcp-linear:linear

Real-World Impact

This would enable CLI usage of:

• Linear MCP - project management
• Slack MCP - team communication
• Any OAuth-protected MCP server
• Enterprise MCP servers with API key authentication

Environment

• OS: Linux (Arch)
• mcptools version: latest (installed via go install)
• MCP server tested: https://mcp.linear.app/mcp

Related

• Linear MCP docs: https://linear.app/docs/mcp
• MCP OAuth spec: https://modelcontextprotocol.io/specification/draft/basic/authorization

Thank you for this excellent tool! Adding header support would make it complete for HTTP-based MCP servers.