mcp-server-setup-and-tool-testing.md

🔧 MCP Server Configuration Guide

This guide explains how to add MCP servers by defining their configuration in JSON format. Each MCP server entry is stored in the database and supports different transport types: stdio, SSE, and StreamableHTTP.

You can add new MCP servers effortlessly through the UI — no need to restart the app. Each tool is available instantly and can be tested independently outside of chat. This is perfect for quick debugging and reliable development workflows.

🖥️ Stdio Type

Used for locally executed tools that run via a command-line interface.

Example:

{
  "command": "npx",
  "args": ["@playwright/mcp@latest"]
}

• command: Required. The CLI command to launch the server.
• args: Optional. A list of arguments to pass to the command.

🌐 SSE / StreamableHTTP Type

Used for remote servers that communicate via HTTP (SSE or streaming).

Example:

{
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer sk-..."
  }
}

• url: Required. The endpoint to connect to.
• headers: Optional. HTTP headers such as authorization tokens.

You don't need to specify the transport type manually — it is inferred based on the structure:

• If command is present → it's a stdio config
• If url is present → it's a SSE or StreamableHTTP config

💾 File-based Configuration (for local dev)

By default, MCP server configs are stored in the database. However, for local development, you can also use a file-based approach by enabling the following setting:

# Whether to use file-based MCP config (default: false)
FILE_BASED_MCP_CONFIG=true

Then, create a .mcp-config.json file in the project root and define your servers there. Example:

// .mcp-config.json
{
  "playwright": {
    "command": "npx",
    "args": ["@playwright/mcp@latest"]
  }
}

Simply paste your configuration in the MCP Configuration form (or .mcp-config.json) to register a new tool.