MCP Servers

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI models interact with external tools and data sources. AQBot acts as an MCP client — you add MCP servers, and the AI can call the tools they expose during a conversation.

---

Transport Protocols

AQBot supports three transport protocols for communicating with MCP servers:

Protocol	Connection	Use Case	Configuration
Stdio	Local process	Tools installed on your machine, launched via npx, uvx, python, etc.	command + args + optional env
SSE	Remote server	Server-Sent Events endpoint hosted on a remote machine or cloud service	url
StreamableHTTP	Remote server	HTTP streaming endpoint, the newer alternative to SSE	url

---

Adding MCP Servers

Form Creation

1. Go to Settings → MCP Servers.
2. Click Add MCP Server.
3. Enter a name and select the transport protocol.
4. Fill in the fields for your chosen protocol:
   • Stdio — command to run, arguments (JSON array), environment variables (JSON object), timeout.
   • SSE — endpoint URL, timeout.
   • StreamableHTTP — endpoint URL, timeout.
5. Click Save.

JSON Import

Click JSON Import and paste a configuration object. AQBot accepts the standard MCP JSON format:

Stdio server

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

SSE server

{
  "mcpServers": {
    "remote-tools": {
      "type": "sse",
      "url": "https://example.com/sse"
    }
  }
}

StreamableHTTP server

{
  "mcpServers": {
    "remote-http": {
      "type": "streamablehttp",
      "url": "https://example.com/mcp"
    }
  }
}

Multiple servers at once

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "remote": {
      "type": "sse",
      "url": "https://example.com/sse"
    }
  }
}

---

Configuration Examples

Web Fetching — mcp-server-fetch

Fetches web pages and converts them to readable text for the AI.

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

File Operations — @modelcontextprotocol/server-filesystem

Gives the AI read/write access to specific directories on your machine.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/documents",
        "/Users/me/projects"
      ]
    }
  }
}

Remote SSE Server

Connect to a remote tool server over Server-Sent Events.

{
  "mcpServers": {
    "cloud-tools": {
      "type": "sse",
      "url": "https://mcp.example.com/sse"
    }
  }
}

Stdio with Environment Variables

Pass API keys or configuration to the server process via environment variables.

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["-m", "weather_server"],
      "env": {
        "WEATHER_API_KEY": "your-api-key"
      }
    }
  }
}

---

Permission Policies

Each MCP server can be assigned a permission policy that controls how tool calls are authorized.

Policy	Behavior
Ask Every Time	A confirmation dialog appears before every tool call. Safest option.
Allow Safe Operations	Read-only operations execute automatically; write or destructive operations require confirmation.
Allow All	All tool calls execute without confirmation. Use only with servers you fully trust.

WARNING

The Allow All policy lets the AI execute any tool — including file writes and shell commands — without asking. Use it only with trusted, well-scoped servers.

---

Built-in Tools

AQBot ships with built-in tools that are available without adding any external MCP server:

Tool	Description
@aqbot/fetch	Fetch web pages and HTTP resources
@aqbot/search-file	Search for files on your local file system

Built-in tools are listed in the MCP Servers settings alongside your custom servers and can be enabled or disabled individually.

---

Tool Execution Panel

When the AI calls an MCP tool during a conversation, AQBot displays a tool execution panel inline in the chat. The panel shows:

• The tool name and the server it belongs to.
• The input arguments sent to the tool.
• The output returned by the tool.
• Execution status (running, succeeded, or failed).

Click on any tool call in the conversation to expand its details. This makes it easy to verify what the AI did and debug unexpected results.

---

Next Steps

• API Gateway — expose your providers as a local API server
• Getting Started — return to the quick start guide