454 lines
11 KiB
Markdown
454 lines
11 KiB
Markdown
# Add WebAccess.MCP to LM Studio
|
|
|
|
This guide explains, step by step, how to add a running WebAccess.MCP server to
|
|
LM Studio's MCP configuration.
|
|
|
|
All PowerShell commands in this guide use **PowerShell (Standard user)**. No
|
|
step requires **PowerShell (Admin)**.
|
|
|
|
WebAccess.MCP uses a remote Streamable HTTP connection. LM Studio connects to:
|
|
|
|
```text
|
|
http://127.0.0.1:28081/mcp
|
|
```
|
|
|
|
It does not launch WebAccess.MCP as a command.
|
|
|
|
## Fast Path After Cloning
|
|
|
|
If Podman Desktop, LM Studio, and a tool-capable model are already installed:
|
|
|
|
1. Open PowerShell in the cloned WebAccess.MCP repository.
|
|
2. Run:
|
|
|
|
```powershell
|
|
.\Start-WebAccessMcp.cmd
|
|
```
|
|
|
|
3. Wait for the script to report that WebAccess.MCP is available.
|
|
4. In LM Studio, open **Program > Install > Edit mcp.json**.
|
|
5. Add this entry inside `mcpServers`:
|
|
|
|
```json
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
```
|
|
|
|
6. Save `mcp.json`.
|
|
7. Click **Refresh** in LM Studio.
|
|
|
|
The startup command creates the local secrets, builds the image, and starts the
|
|
complete PostgreSQL, SearXNG, and WebAccess.MCP stack.
|
|
|
|
## Before You Begin
|
|
|
|
Confirm:
|
|
|
|
- LM Studio 0.3.17 or later is installed.
|
|
- The WebAccess.MCP Podman Compose stack is running.
|
|
- The `webaccess` container is running.
|
|
- Port 28081 is reachable on the local computer.
|
|
- A tool-capable instruct/chat model is installed in LM Studio.
|
|
|
|
Verify WebAccess.MCP from PowerShell:
|
|
|
|
```powershell
|
|
Test-NetConnection 127.0.0.1 -Port 28081
|
|
```
|
|
|
|
The result must include:
|
|
|
|
```text
|
|
TcpTestSucceeded : True
|
|
```
|
|
|
|
If it returns `False`, start or troubleshoot the Podman Compose stack before
|
|
changing LM Studio.
|
|
|
|
## 1. Open LM Studio's MCP Configuration
|
|
|
|
1. Start LM Studio.
|
|
2. Open the **Program** tab in the right sidebar.
|
|
3. Select **Install**.
|
|
4. Select **Edit mcp.json**.
|
|
|
|
Use LM Studio's editor rather than searching for the file in Windows. LM Studio
|
|
opens the correct configuration for the current installation.
|
|
|
|
The top-level JSON structure is:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
}
|
|
}
|
|
```
|
|
|
|
All MCP server definitions belong inside `mcpServers`.
|
|
|
|
## 2. Back Up an Existing Configuration
|
|
|
|
If the editor already contains MCP servers, copy the complete JSON into a
|
|
temporary text file before changing it.
|
|
|
|
Do not share that backup without reviewing it. Other MCP entries can contain
|
|
tokens, API keys, local paths, or environment variables.
|
|
|
|
If the file is empty or contains only an empty `mcpServers` object, continue to
|
|
the next section.
|
|
|
|
## 3. Add WebAccess.MCP to an Empty Configuration
|
|
|
|
Replace the empty configuration with:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The server name is `webaccess`. The name identifies this connection inside LM
|
|
Studio and does not change the server endpoint.
|
|
|
|
## 4. Add WebAccess.MCP Alongside Existing Servers
|
|
|
|
If `mcp.json` already contains servers, do not replace them. Add `webaccess`
|
|
inside the existing `mcpServers` object.
|
|
|
|
For example, starting with:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"example-server": {
|
|
"url": "https://example.com/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Add a comma after the existing server and insert the WebAccess.MCP entry:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"example-server": {
|
|
"url": "https://example.com/mcp"
|
|
},
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
If `webaccess` is not the final entry, add a comma after its closing brace:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
},
|
|
"another-server": {
|
|
"url": "https://example.com/another-mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
JSON does not allow a trailing comma after the final property.
|
|
|
|
## 5. Check the WebAccess.MCP Entry
|
|
|
|
The entry must contain only the HTTP URL:
|
|
|
|
```json
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
```
|
|
|
|
Do not add:
|
|
|
|
- `command`
|
|
- `args`
|
|
- `env`
|
|
- authentication headers
|
|
- a Podman executable path
|
|
- a .NET executable path
|
|
|
|
Do not use these incorrect URLs:
|
|
|
|
```text
|
|
http://127.0.0.1:28080/
|
|
http://127.0.0.1:28081/
|
|
http://searxng:8080/
|
|
http://webaccess:8080/mcp
|
|
```
|
|
|
|
Reasons:
|
|
|
|
- Port 28080 is the SearXNG diagnostic endpoint, not MCP.
|
|
- The required MCP route is `/mcp`.
|
|
- Compose service names such as `searxng` and `webaccess` resolve only inside the
|
|
private container network.
|
|
|
|
Use exactly:
|
|
|
|
```text
|
|
http://127.0.0.1:28081/mcp
|
|
```
|
|
|
|
## 6. Save the Configuration
|
|
|
|
1. Review the complete JSON.
|
|
2. Confirm all object names and string values use double quotes.
|
|
3. Confirm properties are separated by commas.
|
|
4. Confirm there is no trailing comma after the final property.
|
|
5. Save `mcp.json` in LM Studio.
|
|
|
|
LM Studio should parse the file and show `webaccess` in the Program tab. If it
|
|
reports a JSON error, correct the syntax before continuing.
|
|
|
|
## 7. Enable WebAccess.MCP
|
|
|
|
1. Return to the **Program** tab.
|
|
2. Locate `webaccess`.
|
|
3. Enable the server if it is disabled.
|
|
4. Allow LM Studio to connect and discover its tools.
|
|
|
|
When the connection succeeds, LM Studio should discover 15 WebAccess.MCP tools.
|
|
|
|
If LM Studio continues to show a connection error after the JSON is corrected:
|
|
|
|
1. Disable `webaccess`.
|
|
2. Confirm the Podman stack is running.
|
|
3. Enable `webaccess` again.
|
|
4. Restart LM Studio if it does not retry the connection.
|
|
|
|
## 8. Load a Tool-Capable Model
|
|
|
|
WebAccess.MCP makes tools available, but the loaded model decides when and how
|
|
to call them.
|
|
|
|
1. Open **Chat** in LM Studio.
|
|
2. Load an instruct/chat model that supports tool use or function calling.
|
|
3. Use a model with enough context for tool definitions and returned web
|
|
content. At least 16K context is a useful starting point when supported by
|
|
the model and hardware.
|
|
4. Start a new chat after loading the model.
|
|
5. Enable the `webaccess` tools for the chat if LM Studio presents a tool or
|
|
integrations selector.
|
|
|
|
A base completion model without tool support is not suitable.
|
|
|
|
## 9. Test the MCP Connection
|
|
|
|
Ask the model:
|
|
|
|
> Use `web_search` to find the official LM Studio MCP documentation. Return the
|
|
> page title and source URL.
|
|
|
|
Expected behavior:
|
|
|
|
1. LM Studio displays a `web_search` tool call.
|
|
2. WebAccess.MCP sends the search through its dedicated SearXNG service.
|
|
3. The model summarizes the returned results and includes the source URL.
|
|
|
|
Then test the browser-backed tools:
|
|
|
|
> Open the official LM Studio MCP documentation URL, report its page title, and
|
|
> list the first five links.
|
|
|
|
LM Studio should show browser tool calls from WebAccess.MCP.
|
|
|
|
The browser context persists across calls. A later click, typing, or page-read
|
|
operation uses the same application-level browser context unless navigation
|
|
changes it.
|
|
|
|
## 10. Confirm the Tool Count
|
|
|
|
WebAccess.MCP exposes 15 tools. LM Studio's tool view should show 15 tools for
|
|
the `webaccess` server.
|
|
|
|
If the connection succeeds but fewer tools appear:
|
|
|
|
1. Restart the WebAccess.MCP Compose service.
|
|
2. Disable and re-enable `webaccess` in LM Studio.
|
|
3. Restart LM Studio.
|
|
4. Confirm the MCP URL has not been redirected to another service.
|
|
|
|
## 11. Example Configurations
|
|
|
|
### WebAccess.MCP only
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### WebAccess.MCP plus two other remote servers
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
},
|
|
"documentation": {
|
|
"url": "https://example.com/documentation/mcp"
|
|
},
|
|
"issue-tracker": {
|
|
"url": "https://example.com/issues/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer <token>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The example token is only a placeholder for the unrelated example server.
|
|
WebAccess.MCP does not require a token or headers.
|
|
|
|
### WebAccess.MCP plus a local command-based server
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
},
|
|
"local-example": {
|
|
"command": "example-command",
|
|
"args": [
|
|
"--serve"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Only the command-based server uses `command` and `args`. Do not copy those
|
|
properties into the `webaccess` entry.
|
|
|
|
## 12. Troubleshooting
|
|
|
|
### LM Studio says `mcp.json` is invalid
|
|
|
|
Common JSON errors include:
|
|
|
|
- A missing comma between server entries.
|
|
- A trailing comma after the final entry.
|
|
- Single quotes instead of double quotes.
|
|
- A missing closing brace.
|
|
- Adding `webaccess` outside `mcpServers`.
|
|
- Two properties with the same `webaccess` name.
|
|
|
|
Restore the backup if necessary, then add the entry again carefully.
|
|
|
|
### `webaccess` does not appear in the Program tab
|
|
|
|
Confirm the entry is inside the top-level `mcpServers` object and that the file
|
|
saved successfully:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Restart LM Studio after saving if the Program tab does not refresh.
|
|
|
|
### LM Studio reports that WebAccess.MCP is disconnected
|
|
|
|
Verify the stack in PowerShell:
|
|
|
|
```powershell
|
|
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
|
|
podman compose --project-name webaccess-mcp ps
|
|
Test-NetConnection 127.0.0.1 -Port 28081
|
|
podman compose --project-name webaccess-mcp logs --tail 200 webaccess
|
|
```
|
|
|
|
The `webaccess` service must be running and the port test must return `True`.
|
|
|
|
### The model answers without calling a tool
|
|
|
|
1. Confirm the `webaccess` server and its tools are enabled for the chat.
|
|
2. Use an explicit instruction such as "Use the `web_search` tool."
|
|
3. Confirm the model supports tool/function calling.
|
|
4. Start a new chat after changing models or tool settings.
|
|
5. Try a stronger instruct model if the connection works but tool selection is
|
|
unreliable.
|
|
|
|
### `web_search` fails but browser tools work
|
|
|
|
The LM Studio MCP connection is probably healthy. Check the separate SearXNG
|
|
service:
|
|
|
|
```powershell
|
|
Test-NetConnection 127.0.0.1 -Port 28080
|
|
Invoke-RestMethod "http://127.0.0.1:28080/config" | Out-Null
|
|
podman compose --project-name webaccess-mcp logs --tail 200 searxng webaccess
|
|
```
|
|
|
|
External search providers can rate-limit requests or present anti-bot
|
|
challenges. WebAccess.MCP does not bypass those restrictions.
|
|
|
|
### The MCP entry works until the computer restarts
|
|
|
|
The JSON configuration persists, but the Podman machine and Compose services
|
|
must be running.
|
|
|
|
Start them before using WebAccess.MCP:
|
|
|
|
```powershell
|
|
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
|
|
podman compose --project-name webaccess-mcp up --detach
|
|
```
|
|
|
|
Then enable or reconnect `webaccess` in LM Studio if needed.
|
|
|
|
## Quick Reference
|
|
|
|
WebAccess.MCP's complete LM Studio entry is:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Connection checklist:
|
|
|
|
1. Start the Podman machine.
|
|
2. Start the `webaccess-mcp` Compose project.
|
|
3. Verify port 28081.
|
|
4. Start LM Studio 0.3.17 or later.
|
|
5. Open **Program > Install > Edit mcp.json**.
|
|
6. Add the `webaccess` URL entry.
|
|
7. Save valid JSON.
|
|
8. Enable `webaccess`.
|
|
9. Load a tool-capable model.
|
|
10. Test with an explicit `web_search` request.
|