What Is Local-First MCP, and When Do You Need Ingress?
Local-first MCP prefers same-machine loopback and enables ingress only when a web client needs remote access. When to pick Local or Web, less exposure.
Local-first MCP means operating an MCP server by prioritizing communication between client and server on the same machine through a loopback address, rather than exposing the endpoint to the internet by default. In AkiMCP 2.1, Gatekeeper always binds 127.0.0.1, and ingress is enabled only when a Web client genuinely needs remote access.
How do Local and Web differ?
- ◆Local: Postman, Cursor, Claude Code, AGY, Codex, or another same-machine client calls the loopback endpoint without ingress.
- ◆Web: Claude, Grok, ChatGPT, or Gemini running on the web or outside infrastructure needs an internet-reachable address, so ingress is configured.
- ◆Authentication: both routes still require a valid token; loopback does not replace access control.
Example: connecting Codex to the local engine
Append the following to ~/.codex/config.toml (do not overwrite the file) and replace YOUR_LOCAL_ACCESS_TOKEN with the token from the panel. Codex calls the engine over streamable HTTP, with the token inlined so there is no environment variable to export:
[mcp_servers.aki-mcp]
url = "http://127.0.0.1:9999/mcp"
http_headers = { "Authorization" = "Bearer YOUR_LOCAL_ACCESS_TOKEN" }Use 127.0.0.1 rather than localhost: on macOS, localhost can resolve to IPv6 ::1 while the server listens on IPv4 only. The token stays mandatory because a malicious web page in a browser on the same machine can call 127.0.0.1 in the background; without a token, that becomes remote command execution or theft of local files.
Why should ingress not be mandatory?
Mandatory ingress makes a completely local task depend on the network and an unnecessary forwarding layer. Local-first separates the two needs: on-machine work continues without ingress, while Web access is enabled deliberately.
The practical benefits are shorter initial configuration and clearer diagnosis. If Local works but Web does not, the problem is in ingress rather than the MCP core.
When should you enable ingress?
Enable ingress only when the client does not run on the same machine, such as a web AI interface calling tools on a personal computer. While no ingress is attached, the OAuth endpoints of the Web flow in AkiMCP 2.1 return 503 to identify the missing layer, and local /mcp keeps serving normally. An ingress added later (through the panel, the --tunnel flag, or the PUBLIC_ORIGIN variable) takes effect after a restart.
The AkiMCP 2.1 panel groups connectors under Local and Web so this decision appears where configurations are copied. Read the AkiMCP 2.1 release article for the complete change set.