Mac Setup

Connect a Mac MCP Client to AxisMCP.

AxisMCP shows the current address and connection password in Connect. Use Streamable HTTP with a Bearer token first; raw TCP is only for advanced clients that understand length-prefixed JSON-RPC frames.

Join the Same Wi-Fi

Your Mac and iPhone or iPad need to be on the same local network, or on a network path you intentionally configure.

Open Connect in AxisMCP

Use the Home toolbar or Settings to open Connect. Copy the current address and reveal the connection password only when needed.

Paste the Matching Config

Use Streamable HTTP at /mcp with your connection password as the Bearer token.

Preferred

Streamable HTTP

If your Mac resolves the device .local hostname, use that URL for a steadier setup. Otherwise replace <device-name>.local with the current address shown in Connect, then set AXISMCP_TOKEN to the connection password.

Clients with Bonjour support can discover AxisMCP (_axismcp._tcp). Clients without discovery should use the explicit HTTP URL.

Cursor or VS Code

.cursor/mcp.json or .vscode/mcp.json

{
  "mcpServers": {
    "axismcp": {
      "url": "http://<device-name>.local:5648/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AXISMCP_TOKEN}"
      }
    }
  }
}

Claude Code

Snippet

claude mcp add --transport http axismcp http://<device-name>.local:5648/mcp --header "Authorization: Bearer $AXISMCP_TOKEN"

Codex

~/.codex/config.toml

[mcp_servers.axismcp]
url = "http://<device-name>.local:5648/mcp"
http_headers = { Authorization = "Bearer ${AXISMCP_TOKEN}" }
startup_timeout_sec = 20
tool_timeout_sec = 180
enabled = true

Fallback

Stdio-Only Clients

Claude Desktop and older clients may need a stdio-to-HTTP bridge. Point that bridge at the same `/mcp` URL and pass your password as the Bearer token.

Raw TCP Is Advanced Only

AxisMCP can accept raw TCP JSON-RPC, but frames are length-prefixed with a 4-byte big-endian unsigned integer. Do not use one-line socket snippets as an MCP configuration unless the bridge handles that framing and authentication.

Troubleshooting

If a Client Cannot Connect

Local Network Permission

If your iPhone or iPad asks for Local Network access, allow it. Without that permission, Mac MCP clients cannot reach the server on your device.

Cellular-Only Device

Nearby computers cannot connect while the device is cellular-only. Join Wi-Fi or use Personal Hotspot and connect the Mac to it.

Address Changed

Network addresses can change. Use a resolvable .local hostname when your Mac supports it, or reopen Connect and copy the current address.

Password Rotated

Creating a new connection password disconnects existing clients. Update AXISMCP_TOKEN on every trusted Mac client.

Apple Intelligence Unavailable

MCP connection can still work, but Chat and inference tools need supported hardware, region, language, and Apple Intelligence enabled in Settings.

VPN or Tailscale

Bonjour discovery may not cross VPNs. Use the explicit VPN or Tailscale address shown in Connect if available.

Contact Support