WebSession MCP Bridge

Giving an AI agent a shell is easy. Knowing exactly what authority you gave it is the real system.

• Problem: A web AI session needs access to real development tools without turning “connected” into an ambiguous permission level.
• Decision: Split access into explicit trust profiles and capability domains, then keep the internet-facing layer narrow.
• Proof: The current bridge separates Dev, Code, Terminal, and Local/Browser capabilities, uses OAuth at the MCP boundary, and keeps durable terminal and adapter lifetimes independent from normal bridge requests.
• Status: active infrastructure; the public surface remains deliberately narrower than the private development harness.

What it does

WebSession MCP Bridge connects AI clients to a Linux or WSL development machine. Native MCP clients use the main 1MCP gateway; an optional WebSession adapter gives constrained non-MCP clients a narrower HTTPS facade without bypassing that gateway’s authority.

The point is not remote shell access by itself. The point is being able to answer: what can this session do, and where does that authority stop?

The trust model is the product

The bridge has three useful operating levels:

• restricted keeps ordinary file operations workspace-bounded.
• trusted-dev deliberately adds native Bash authority for a dedicated development host.
• personal composes the fuller private WSL harness, including repository intelligence, durable terminal sessions, host sleep, and explicitly scoped browser control.

Those are not cosmetic modes. They are different authority contracts. A public installation should not silently inherit the permissions of my private development machine.

Durable terminals solved a different problem

Short MCP calls and long-running development processes have different lifetimes. A build, server, or interactive terminal should not disappear just because an MCP provider restarts or one HTTP request ends.

The bridge therefore keeps terminal PTYs under tmux and treats terminal ownership as a separate boundary. That lets a model start a real process, observe it later, and hand the same PTY to a human when input is required instead of inventing another shell path.

Browser control stays behind a stable broker

The personal profile does not publish a large browser catalog directly beside files and Bash. It exposes three Local broker actions—discovery, schema lookup, and invocation—while a private inner 1MCP and Browser facade choose the authorized native Windows or WSLg Chrome target.

That keeps browser routing resource-local and lets the outer model-facing schema stay stable when the downstream browser catalog changes.

The optional adapter reuses the same authority

Some AI clients can make HTTPS requests but do not provide native MCP. The separately started WebSession adapter supports those clients through readable GET and bearer-authenticated JSON POST facades backed by durable SQLite operations.

It authenticates back to 1MCP, mirrors live tool metadata, and invokes the exact upstream tools. It has its own manual lifecycle and capability revocation, but it does not become a second tool-permission system.

A smaller surface was easier to reason about

The private harness keeps three direct domains plus one Local broker domain instead of exposing every implementation primitive as an unrelated tool. Dev owns file and command work. Code owns repository intelligence. Terminal owns persistent interactive processes. Local owns stable routing to resource-specific capabilities such as Browser.

That separation became more important as the bridge grew. The useful question was no longer “can the model execute this?” but “which boundary already owns this action?”

Public and private are intentionally different

The repository keeps a publication boundary between general-purpose profiles and private personal-harness implementation/evidence. Public users can start from a bounded profile instead of copying the authority of my own machine by accident.

That is also why bootstrap and persistent startup are explicit. Preparing a runtime and enabling a service to come back automatically are different decisions and should look different in the interface.

Current state

The released Phase-2 harness remains the baseline, while the current repository adds the Local/Browser boundary, selectable terminal presentation, explicit Windows host sleep, and the optional WebSession adapter. The project remains a self-hosted development bridge, not a hosted multi-tenant service.

Note: WebSession MCP Bridge is an independent educational experiment exploring controlled AI-to-development-environment access. It is not designed or intended to bypass OpenAI safeguards or violate OpenAI’s Terms of Use or platform policies.

What I learned

The most valuable part of agent infrastructure is often not another capability. It is a clean answer to ownership, lifetime, and authority.

A tool surface becomes easier to trust when access is explicit, long-running state has one owner, and a private convenience does not quietly become a public default.

Links

• Repository