MCP Setup

Connect HeadlessX to the remote MCP endpoint with dashboard-created API keys and current operator tools.

by @saifyxpro

HeadlessX MCP Setup

HeadlessX exposes a remote MCP endpoint from the backend:

Use a normal API key created from the dashboard API keys page. Do not use DASHBOARD_INTERNAL_API_KEY.

What MCP is used for

Use MCP when the client is agent-driven and benefits from tool discovery, structured inputs, and server-side capability descriptions.

Typical clients:

  • Claude Desktop or hosted Claude-compatible clients
  • Cursor
  • OpenClaw
  • Open WebUI
  • custom remote MCP consumers

Endpoint

Local development

Production example

Authentication

Send the same API key you created from the dashboard:

Use a normal API key

MCP clients should authenticate with a dashboard-created API key. The internal dashboard key is reserved for the web proxy path and should not be reused in external clients.

MCP does not accept:

  • DASHBOARD_INTERNAL_API_KEY

JSON client config

TOML client config

What tools are exposed

Current phase-one MCP coverage includes:

  • website extraction and content tools
  • Google AI Search
  • Tavily search and research
  • Exa search
  • YouTube extract metadata, formats, and subtitles
  • job status tools

Requirements

MCP depends on the same backend services as the underlying HTTP routes:

  • API must be running
  • PostgreSQL must be available for API key validation
  • Redis and the worker are required for queue-backed job tools
  • YT_ENGINE_URL is required for YouTube MCP tools

Recommended workflow

  1. create an API key in the dashboard
  2. confirm the backend is reachable at /mcp
  3. add the client config in JSON or TOML
  4. verify the client can discover HeadlessX tools

Troubleshooting

Related Docs

Agent Skills

Use the repository skill when the agent should drive the published CLI instead of remote MCP.

API Reference

Review the backend route families, auth model, and transport patterns.

Next Steps

Integrations

Choose how HeadlessX fits into HTTP clients, workflow tools, and application code.

Jobs API

Inspect queue-backed jobs and understand the status and polling model.