MCP Server - Configuring Claude

Intended audience: USERS Developers administrators

AO Platform: 5.0

Configuring Claude

AO tools can run for a long time (natural-language SQL generation, large executes, full schema export). The MCP server enforces app.platform.semantic-sql-tool-timeout (often 120s by default in docs; your deployment may use a higher value). The AO Platform HTTP client also uses read-timeout-millis, which can be several minutes. Your MCP client has its own timeout: if the client gives up before the server finishes, you will see a failed tool call even when the server would have succeeded.

Rule of thumb: Set the client MCP tool timeout to at least the larger of: server semantic-sql-tool-timeout, platform read timeout, plus a small buffer. Example: if the server allows 250s for tools and the platform read timeout is 480s, configure the client for ≥ 480s (8 minutes) or more for heavy workflows.

Claude Desktop

Config file locations

MCP server configuration

{
  "mcpServers": {
    "ao-mcp-server": {
      "command": "npx",
      "type": "http",
      "args": [
        "-y", "ao-mcp-bridge@latest", "http://localhost:8080/mcp",
        "--header", "X-Platform-Api-Key:ak_YOUR_PLATFORM_API_KEY_HERE",
        "--timeout", "600"
      ]
    }
  }
}

Restart Claude Desktop after saving the file.

Timeout configuration

Claude Desktop does not currently expose a user-configurable MCP tool timeout in claude_desktop_config.json. If long-running tools (e.g., nlq-to-semantic-sql, export-ontology-schema) fail with timeout errors while the server is still processing, consider the following workarounds:

• Switch to Claude Code (CLI), where MCP_TIMEOUT can be set explicitly (see below).

• Lower the server-side timeout (app.platform.semantic-sql-tool-timeout) to fit within the Claude Desktop default, accepting that some heavy operations may need to be split into smaller calls.

• Break large queries into smaller, faster tool calls (e.g., use incremental schema tools instead of export-ontology-schema).

Claude Code (CLI)

MCP server configuration

Claude Code reads the MCP server configuration from .mcp.json at the project root or from global settings. Create or edit .mcp.json:

{
  "mcpServers": {
    "ao-mcp-server": {
      "command": "npx",
      "args": [
        "-y", "ao-mcp-bridge@latest", "http://localhost:8080/mcp",
        "--header", "X-Platform-Api-Key:ak_YOUR_PLATFORM_API_KEY_HERE",
        "--timeout", "600"
      ]
    }
  }
}

Timeout configuration

Set the MCP_TIMEOUT environment variable (in milliseconds) before starting Claude Code. This controls how long the client waits for any MCP tool call to complete.

Linux / macOS

export MCP_TIMEOUT=600000
claude

Windows (Command Prompt)

set MCP_TIMEOUT=600000
claude

Windows (PowerShell)

$env:MCP_TIMEOUT = "600000"
claude

Recommended Values

Tip: Confirm the exact environment variable name and unit in the []() for your installed version, as these may evolve across releases.

Cowork (Claude Desktop — Cowork Mode)

When using Claude through Cowork mode, MCP servers are configured via the Cowork plugin system rather than manual JSON files. Timeout behavior follows the Claude Desktop defaults. If tool calls are timing out:

• Ensure the AO MCP Server's app.platform.semantic-sql-tool-timeout is set to a reasonable value (e.g., 120–250s).

• Prefer incremental schema discovery tools over `export-ontology-schema`.

• Break complex queries into smaller steps to stay within the default timeout window.

Contact App Orchid | Disclaimer