#MCP Servers

Wingman supports Model Context Protocol (MCP) servers via stdio or sse transports.

#Global MCP config

{
  "mcp": {
    "servers": [
      {
        "name": "local-tools",
        "transport": "stdio",
        "command": "node",
        "args": ["/path/to/server.js"],
        "env": {
          "API_KEY": "..."
        }
      },
      {
        "name": "remote-tools",
        "transport": "sse",
        "url": "http://localhost:8000/mcp",
        "headers": {
          "Authorization": "Bearer ..."
        }
      }
    ]
  }
}

#Per-agent MCP config

{
  "name": "researcher",
  "description": "Uses a custom MCP server.",
  "systemPrompt": "Use MCP tools for retrieval.",
  "mcp": {
    "servers": [
      {
        "name": "papers",
        "transport": "sse",
        "url": "https://mcp.example.com/papers"
      }
    ]
  },
  "mcpUseGlobal": true
}

#Transport types

• stdio: spawn a local subprocess and communicate over stdio.
• sse: connect to a remote HTTP/SSE endpoint.

Keep MCP servers scoped to the minimum data and permissions required for each agent.

#Resource discovery tools

When an agent has MCP configured, Wingman also injects two MCP resource helper tools:

• mcp_list_resources: list resources for all configured MCP servers (optionally include templates)
• mcp_read_resource: read a specific resource URI from a specific MCP server

These tools are additive and do not change the behavior of existing MCP tool calls (including FAL and finance servers).

#Finnhub finance MCP server

Use the bundled finance MCP server to power market-data agents (like stock-trader) with quotes, candles, fundamentals, news, and option chains.

#1) Provide a Finnhub API key

The finance MCP server requires FINNHUB_API_KEY. You can set it globally in your shell or inline per server config.

#2) Register the server (stdio example)

{
  "mcp": {
    "servers": [
      {
        "name": "finnhub",
        "transport": "stdio",
        "command": "node",
        "args": [
          "./node_modules/@wingman-ai/gateway/dist/tools/mcp-finance.js"
        ],
        "env": {
          "FINNHUB_API_KEY": "your_key_here",
          "FINNHUB_CANDLES_PROVIDER": "yahoo"
        }
      }
    ]
  }
}

If you are working from the Wingman repo directly, the server file is located at:

apps/wingman/dist/tools/mcp-finance.js

#3) Enable MCP for your agent

Set mcpUseGlobal: true in agent.json/agent.md or add a per-agent mcp block.

#Optional environment variables

Use these to fine-tune rate limits and candle data behavior:

FINNHUB_API_KEY                 # required
FINNHUB_CANDLES_PROVIDER        # yahoo | finnhub | auto (default: yahoo)
FINNHUB_CANDLE_MAX_DAYS_INTRADAY # default: 30
FINNHUB_CANDLE_MAX_DAYS_DAILY    # default: 365
FINNHUB_RATE_LIMIT_PER_MIN       # default: 60 (or tier-based)
FINNHUB_TIER                     # e.g. free
FINNHUB_TIER_LIMITS              # JSON override, e.g. {"free":60,"pro":300}
FINNHUB_BASE_URL                 # default: https://finnhub.io/api/v1
YAHOO_FINANCE_BASE_URL           # default: https://query1.finance.yahoo.com
YAHOO_INCLUDE_PREPOST            # set to 1 to include pre/post market candles

#FAL AI MCP server

Use the bundled FAL AI MCP server for queue-backed multimodal generation (image, image edit, audio/music, and video from image).

#1) Provide a FAL API key

Set FAL_API_KEY (or FAL_KEY) in your shell or inline in the MCP server config.

#2) Register the server (stdio example)

{
  "mcp": {
    "servers": [
      {
        "name": "fal-ai",
        "transport": "stdio",
        "command": "node",
        "args": [
          "./node_modules/@wingman-ai/gateway/dist/tools/mcp-fal-ai.js"
        ],
        "env": {
          "FAL_API_KEY": "your_key_here",
          "FAL_MCP_REVIEW_MODE": "auto",
          "FAL_MCP_POLL_INTERVAL_MS": "2500",
          "FAL_MCP_STATUS_TIMEOUT_MS": "60000",
          "FAL_MODEL_IMAGE_OR_TEXTURE": "fal-ai/nano-banana-pro",
          "FAL_MODEL_IMAGE_EDIT": "fal-ai/kling-image/v3/image-to-image",
          "FAL_MODEL_AUDIO_OR_MUSIC": "fal-ai/elevenlabs/music",
          "FAL_MODEL_SOUND_EFFECT": "beatoven/sound-effect-generation",
          "FAL_MODEL_VIDEO_FROM_IMAGE": "fal-ai/kling-video/o3/standard/image-to-video"
        }
      }
    ]
  }
}

If you are working from the Wingman repo directly, the server file is located at:

apps/wingman/dist/tools/mcp-fal-ai.js

#3) Use it from agents

• generate_image_or_texture
• generate_image_edit
• generate_audio_or_music
• generate_video_from_image
• fal_generation_status

Default local paths:

<workdir>/generated/
<workdir>/.wingman/fal-ai/

If FAL_MCP_REVIEW_MODE=hil, completed jobs are staged under <workdir>/.wingman/fal-ai/pending/<jobId>/ until fal_generation_status is called with action=accept or action=deny.

Assistant message images are also materialized to disk from session history under:

<stateDir>/agents/<agentId>/sessions/media/<sessionId>/