Mach5 One MCP Guide

Mach5 One exposes a Model Context Protocol (MCP) endpoint so AI agents can use the local Mach5 One server.

This page covers the local Mach5 One MCP endpoint. MCP workflows and Mach5 concepts exposed through MCP are common Mach5 capabilities unless documented as Mach5 One-specific runtime behavior.

Endpoint

Start Mach5 One:

mach5-one start

MCP endpoint:

http://localhost:8080/mcp

Use the configured server.http_port if you changed the HTTP port.

Client configuration

Example client configurations live in:

examples/agent-configs/

Use an MCP client that supports connecting to an HTTP MCP endpoint, and configure a server named mach5-one with the URL above.

Agent workflow

Agents should:

1. Confirm the server is running with /version.txt.
2. Connect to /mcp.
3. Discover available tools, resources, and prompts.
4. Ask before loading local files or accessing sensitive data.
5. Prefer targeted queries over broad data dumps.
6. Report reproducible runtime issues with logs and environment details.

Security model

Mach5 One runs on the user’s machine. Treat local files, loaded data, credentials, and query results as user-controlled data.

Agents must:

• Ask before loading local files.
• Avoid sending sensitive local data to unrelated services.
• Explain what data will be read or loaded.
• Follow the user’s security boundaries.

Troubleshooting MCP

If an MCP client cannot connect:

1. Confirm Mach5 One is running.

2. Confirm the MCP URL uses the configured HTTP port.

3. Check for port conflicts.

4. Check runtime logs.

5. Test the version endpoint:

   curl http://localhost:8080/version.txt
   

Collect for issue reports:

• Mach5 One version
• MCP client name and version
• OS and architecture
• Client config with secrets removed
• Startup command
• Error message
• Runtime logs

Related files

• agent-quickstart.md
• ../AGENTS.md
• ../examples/agent-configs/