# House Rails MCP

House Rails MCP is a public-safe coordination boundary for a house worker that can ride named rails between local house services, Cloudflare, and model families such as OpenAI, Anthropic, Perplexity, xAI, and Cursor.

The first release is deliberately read-only. It exposes an MCP server over Cloudflare Workers Streamable HTTP and provides tools for:

- describing the public capability manifest;
- running a deterministic arrival check;
- previewing a route without contacting a provider;
- checking the local tree for common private material before publication.

Provider adapters, credentials, private destinations, and execution permissions belong in the in-house layer. They are not part of this public repository.

## Run locally

Requires Node.js 20 or newer.

```bash
npm install
npm run check
npm run dev
```

The local endpoint is usually `http://localhost:8788/mcp`. Use the MCP Inspector or any client that supports Streamable HTTP.

## Deploy to Cloudflare

Authenticate Wrangler with the Cloudflare account that owns the Worker, then deploy:

```bash
npx wrangler login
npm run deploy
```

The deployed endpoint is:

```text
https://<worker-name>.<account-subdomain>.workers.dev/mcp
```

The initial server is intentionally authless because its tools do not read account data, call providers, or mutate external systems. Add Cloudflare Access or OAuth before adding any tool that reads private state or executes a route. Cloudflare's remote MCP guide describes the supported authentication paths.

## MCP tools

`house_manifest` returns the public protocol, destination families, and privacy posture.

`house_arrival_check` checks whether a requested set of rails is represented in the public manifest. It reports configuration and authentication as deferred until the in-house layer supplies them.

`house_route_preview` turns a task and destination into a reviewable route plan. Preview mode is the only mode enabled in this public release; execute requests return a blocked plan with the next in-house step.

## Client configuration

For a client that supports remote MCP URLs, use the deployed `/mcp` endpoint. For a local-only client, `mcp-remote` can bridge the same endpoint:

```json
{
  "mcpServers": {
    "house-rails": {
      "command": "npx",
      "args": ["mcp-remote", "https://<worker-name>.<account-subdomain>.workers.dev/mcp"]
    }
  }
}
```

## Public release boundary

Before publishing, run:

```bash
npm run arrival:check
npm run scan:public
```

The scanner blocks private key material, token-shaped values, local user paths, and identity-shaped IDs. Keep real credentials in Wrangler secrets or the in-house deployment environment. Do not add `.env`, `.dev.vars`, account identifiers, custom domains, or private adapter code to this tree.

## Project layout

```text
src/house.ts                         Pure routing and arrival logic
src/index.ts                         Cloudflare Worker and MCP tools
scripts/arrival-check.mjs            Arrival gate used by the local skill
scripts/public-surface-check.mjs     Public-release privacy scan
.codex/skills/house-arrival-check/   Skill instructions for agents on entry
```

## License

MIT. See [LICENSE](LICENSE).

## References

- [Cloudflare remote MCP server guide](https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/)
- [Cloudflare MCP handler API](https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/)
- [MCP transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)