Connecting an AI agent to Einfall

Einfall's Mac app can run a small local server that gives an AI agent — one you already use, on your own machine — the same access to your stream you have yourself: reading thoughts, tagging them, and firing the actions you've set up. It's off by default. Turn it on in Settings · External Agents.

This page is the setup reference the app deliberately doesn't try to bake in — per-client configuration formats change faster than an App Store release cycle, so recipes live here instead of in the app.

The two things every client needs

Whatever agent or tool you're connecting, it needs exactly two facts, both shown as copyable fields in Settings · External Agents:

1. The endpoint URL — where the server is listening, e.g. http://127.0.0.1:PORT/mcp.

2. The bearer token — a private access token, generated on your Mac, that authorises requests to that endpoint.

Every recipe below is just a different way of handing those same two facts to a different piece of software.

Worked example: Claude Code

With External Agents turned on and the endpoint + token copied from Settings, run:

claude mcp add --transport http einfall http://127.0.0.1:PORT/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

• --transport http tells Claude Code this is a remote (HTTP) MCP server rather than a local command.

• einfall is just a name you're choosing for this connection — call it whatever you like.

• Replace PORT and YOUR_TOKEN with the values shown in Settings · External Agents.

• This registers the server for the current project by default (local scope). Add --scope user if you want it available in every project on your Mac.

Once added, ask Claude Code to list or search your Einfall stream — it can now read your thoughts and fire the actions you've configured, the same as if you'd done it by hand in the app.

Generic recipe: any MCP-over-HTTP client

Any tool that speaks the Model Context Protocol over HTTP needs the same configuration, typically expressed as JSON along these lines:

{
  "mcpServers": {
    "einfall": {
      "url": "http://127.0.0.1:PORT/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Check your client's own documentation for exactly where this configuration goes — the shape above (a URL plus an Authorization: Bearer header) is the constant; the file name and location vary by client.

The honest constraint: this only works from the same Mac

The server binds to 127.0.0.1 — loopback only. A cloud-hosted agent cannot reach it, structurally, no matter how the connection is configured: there is no public address for it to reach, by design. This means:

• An agent running as a local process or CLI on the same Mac the Einfall server is running on: works, as in the Claude Code example above.

• A cloud-hosted agent product, a hosted automation platform, or an agent running on a different machine: cannot connect, and no amount of configuration changes that.

If your agent runs somewhere other than the Mac itself, External Agents isn't the right path for it — the run-shortcut action (wiring a non-Apple AI provider in via a Shortcut) is the escape hatch for that case.

Security notes

• Off by default. Every fresh install ships with External Agents turned off. Turning it on is a deliberate choice, made once, in Settings.

• Loopback-only. The server only accepts connections from the Mac it's running on — there is no local-network or remote-network exposure.

• Token-protected. Every request must carry the bearer token shown in Settings. The token is generated on-device and stored in the system Keychain.

• Regenerate anytime. If you ever want to cut off an existing connection, hit Regenerate in Settings · External Agents — the server restarts with a new token in place, and any client using the old one stops working immediately.

• Independent of the app lock. If you use Einfall's optional biometric lock on the stream view, note that it protects the app's own UI only — an agent already authorised via External Agents can still read and write the stream regardless of whether the app itself is locked. Turning off External Agents (or regenerating the token) is the actual off switch.

The routing gate applies to agents too

Actions an agent fires through this server count toward the same 15 free routing fires as actions you fire by hand in the app — capability parity means an agent can do anything you can do, under the same rules. Once the free fires are used, a routing action attempted through an agent doesn't fail silently: it returns a documented error, Routing is locked, telling the agent (and you) exactly what happened and that the one-time $29.99 unlock removes the limit. Reading the stream and non-routing operations (search, listing, tagging) are never gated.