webaccess-mcp/QUICKSTART.md

4.0 KiB

WebAccess.MCP Quick Start

Use this guide when the computer already has:

  • Podman Desktop with a running Podman machine.
  • Podman Compose.
  • LM Studio 0.3.17 or later.
  • A tool-capable model installed in LM Studio.
  • Git.

All commands in this quick-start use PowerShell (Standard user). Do not run PowerShell as an administrator for this workflow.

1. Clone the Repository

PowerShell (Standard user)

$McpRoot = Join-Path $env:SystemDrive "ai\mcp"
New-Item -ItemType Directory -Force -Path $McpRoot | Out-Null
Set-Location $McpRoot
git clone <repository-url> WebAccess.MCP
Set-Location ".\WebAccess.MCP"

Replace <repository-url> with the repository URL supplied by the project owner.

$env:SystemDrive uses the Windows system drive, which is normally C:. The resulting default repository location is:

C:\ai\mcp\WebAccess.MCP

To use another local drive, set $McpRoot explicitly before cloning:

PowerShell (Standard user)

$McpRoot = "E:\ai\mcp"

2. Start the Entire Stack

From the cloned repository root, run one command:

PowerShell (Standard user)

.\Start-WebAccessMcp.cmd

The command:

  1. Verifies Podman and Podman Compose.
  2. Creates local installation secrets if they do not exist.
  3. Builds the WebAccess.MCP container image.
  4. Starts PostgreSQL, SearXNG, and WebAccess.MCP.
  5. Displays container status and the local endpoint.

The first build can take several minutes.

If an earlier startup created failed or incomplete containers, running the same command again replaces them with the corrected stack.

When startup succeeds, the MCP endpoint is:

http://127.0.0.1:28081/mcp

The startup command does not report success until this health endpoint responds:

http://127.0.0.1:28081/health

3. Add WebAccess.MCP to LM Studio

  1. Open LM Studio.
  2. Open the Program tab in the right sidebar.
  3. Select Install > Edit mcp.json.
  4. Add webaccess inside the existing mcpServers object.

For an empty configuration, use:

{
  "mcpServers": {
    "webaccess": {
      "url": "http://127.0.0.1:28081/mcp"
    }
  }
}

If other MCP servers already exist, preserve them and add:

"webaccess": {
  "url": "http://127.0.0.1:28081/mcp"
}

Include a comma between server entries. Do not add command, args, headers, or a Podman path to the webaccess entry.

  1. Save mcp.json.
  2. Click Refresh in LM Studio.
  3. Confirm that webaccess is connected and exposes 15 tools.

4. Test It

Load the tool-capable model and ask:

Use web_search to find the official LM Studio MCP documentation and return the source URL.

LM Studio should display a web_search tool call.

Normal Startup After a Restart

Start Podman Desktop and its Podman machine, then run from the repository root:

PowerShell (Standard user)

.\Start-WebAccessMcp.cmd

The command is safe to run again. It preserves the existing secrets and PostgreSQL page cache.

Stop the Stack

From the repository root:

PowerShell (Standard user)

Set-Location ".\deploy"
podman compose --project-name webaccess-mcp stop

If Startup Fails

Check Podman:

PowerShell (Standard user)

podman info
podman compose version

Check the stack:

PowerShell (Standard user)

Set-Location ".\deploy"
podman compose --project-name webaccess-mcp ps --all
podman compose --project-name webaccess-mcp logs --tail 200

Test the HTTP server itself:

PowerShell (Standard user)

Invoke-RestMethod "http://127.0.0.1:28081/health"

Expected result:

status
------
healthy

Do not use a plain browser request or curl GET to /mcp as the health test. /mcp expects MCP protocol requests and can return a protocol or method error even when the server is reachable. Use /health to test connectivity and LM Studio to test the MCP handshake.

For detailed instructions, see:

  • docs\Standing-Up-the-Podman-Compose-Stack.md
  • docs\Adding-WebAccess-MCP-to-LM-Studio.md