Bridge

English | 日本語

Experimental. This came in with framework 1.4.0 and may change or go away in a later version.

The Bridge (DragNWash.ModFramework.Bridge, version 1.5.0) lets AI clients on your computer, such as Claude Code, VS Code and Cursor, read the running game through the Model Context Protocol (MCP). They can see objects and their values, the log, the mods, the saves and the dialogue, but they can't change anything. It's there for people who make or debug mods, and players never need it.

It's been tested on Windows and on the Steam Deck (the game's native Linux build).

Design: docs/BRIDGE.md

Off unless you turn it on

• The Bridge is a library of its own, next to the core and the Tool window, and it needs both of them. A mod's release can leave it out, and a player's install won't have it unless they add it.
• It's off by default, and it only runs while Developer tools are on (Options → Mods → Drag'n Wash ModFramework). Turning either one off closes it and disconnects every client.
• It listens on this computer only, and it's read-only.

Turning it on

You can use any of these. They all change the same setting.

• Turn on in the panel at the top of the Bridge tab in the F1 window.
• On the Mods screen: Mods → Drag'n Wash ModFramework: Bridge → Settings → Let AI clients read the game (MCP) ([Bridge] Enabled).
• bridge on in the Console.

Once it's on, it listens at http://127.0.0.1:47821/mcp. The port comes from [Bridge] Port (an advanced setting, 1024 to 65535). If the port can't be used, the Bridge tab says why and can move it for you. See When the port can't be used below.

While the Bridge is listening, the game keeps running even when its window isn't in front, so a client can still get answers. When the Bridge stops, the game's own setting comes back.

Setting up a client

The Setup row on the Bridge tab has a button for each client: Claude Code, VS Code and Cursor. Pick yours and press Copy setup, and the setup goes on the clipboard with your token and your current port filled in (1.5.0). Below, <token> stands for your token and 47821 is the default port. You only do this once. After a New token or a new port you do it again.

Claude Code

Run this in a terminal:

claude mcp add --transport http dragnwash http://127.0.0.1:47821/mcp --header "Authorization: Bearer <token>"

If dragnwash is already set up in Claude Code (say, after a new token or a new port), run claude mcp remove dragnwash first. Adding the same name twice fails.

VS Code

This goes in .vscode/mcp.json in your project (1.5.0). If the file already lists other servers, add just the dragnwash entry to them.

{
  "servers": {
    "dragnwash": {
      "type": "http",
      "url": "http://127.0.0.1:47821/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Cursor

This goes in .cursor/mcp.json in your project, or in ~/.cursor/mcp.json to have it in every project (1.5.0). Again, if the file lists other servers, add just the dragnwash entry.

{
  "mcpServers": {
    "dragnwash": {
      "url": "http://127.0.0.1:47821/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

You can copy a setup while the Bridge isn't listening yet, so you can set a client up ahead of time. The notice then reminds you it won't answer until the Bridge is listening.

What a client can do

It can only look. Every read operation in the Operations registry becomes one tool, with its description and parameters (the dots become _, so inspector.member.get is the tool inspector_member_get). With the core and all the libraries installed that's 22 tools, such as game_info, scene_list, mods_list, log_read, inspector_objects_find, inspector_member_get, saves_flags_list, dialogue_recent and text_shown. The full list is on the Operations page.

• Write operations are never offered.
• Operations that show the game's own code (the code graph) are only for the page on this computer, never for an AI client.
• No files are read or written for a client. It only gets what the operations return.
• Calls run in the game one at a time, and show up in the log as mcp:<client name>.

Safety

• This computer only. The Bridge listens on 127.0.0.1 and nowhere else, so no other computer can connect, and Windows doesn't ask to open the firewall.
• A token. Every request needs Authorization: Bearer <token>. The token is made the first time the Bridge starts and kept in your user profile, not in the game folder. That's %LOCALAPPDATA%/DragNWash ModFramework/bridge-token.txt on Windows and ~/.local/share/DragNWash ModFramework/ on Linux and the Steam Deck. The Bridge tab never shows it on screen, so it's safe on a stream or in a screenshot. You can only copy it.
• Web pages cannot call it. A request whose Host isn't 127.0.0.1:<port> or localhost:<port> is refused (that would be a website pointing its own name at your computer), and so is any request with an Origin, which a browser adds.
• Limits. There can be at most 8 connections and 4 clients at once, and a client that's idle for 30 minutes is ended. One client can make at most 20 calls a second. Requests can be up to 1 MB and results up to 200,000 characters, and a call that takes more than 10 seconds in the game returns a time-out error.
• New token (on the Bridge tab, or bridge token new) makes a new token and disconnects every client, so you'll need to set them up again with Copy setup. Use it if the token may have leaked. On the tab it asks first when a client is connected, and names who it'll cut off (1.5.0).
• Disconnect all (on the Bridge tab, or bridge disconnect) ends every client's connection. On the tab it asks first when a client is connected (1.5.0). A client can connect again with the same token.

When the port can't be used

(1.5.0)

When the Bridge can't listen, the panel at the top of the Bridge tab turns red, and its title names the port so a screenshot carries it. There are two usual reasons.

• "Not listening: Windows won't let the game use port 47821" means Windows has set the port aside. Hyper-V, WSL and Docker keep ranges of ports for themselves, and which ones can change when the PC restarts. The log says the same thing.
• "Not listening: port 47821 is in use" means another program probably has it.

Anything else shows the system's own message. The red panel has Use a free port, Try again and Turn off.

Use a free port looks at up to 200 ports after the current one. On Windows it skips every range in Windows' excluded port list (it reads netsh interface ipv4 show excludedportrange protocol=tcp, which needs no administrator), and it skips any port it can't listen on for a moment on 127.0.0.1. The first good one is saved as [Bridge] Port and the Bridge listens there. It only asks: nothing in Windows' settings changes, the Bridge still listens on 127.0.0.1 only, and it still needs the token. A notice then says something like "Listening on port 47822 now. Clients set up for 47821 need the new setup (Copy setup).", and a yellow line under the address says "Port changed from 47821. Set your client up again with Copy setup." That line stays until you copy the address or a setup, or a client connects. If none of the 200 ports is free, it tells you to try again after the PC restarts.

Try again tries the same port once more, which helps after a restart when Windows has let the port go.

Turn off clears the old failure, so the panel just says Off.

What you see

• The Bridge tab (F1) (1.5.0) starts with a panel that says whether the Bridge is listening. Its bar is the accent colour with "Listening on 127.0.0.1:47821", dim with "Off", and red with the reason when it can't listen. Turn on and Turn off are in that panel.
• Under it, CONNECTION has a row each for the address, the token and the setup, and each row has its own Copy. The token row says it's kept in your user profile and never shown, and has New token beside Copy. The Setup row has the three clients and Copy setup, with a short note on where the setup goes.
• CODE GRAPH has Code graph and Graphs editor, which open the page. On Windows, "Opens in" lets you switch between App and Browser right there. Both buttons are greyed out with "Opens once the Bridge is listening." until it is.
• CLIENTS lists who is connected, by the name they gave, with how many calls they made and when the last one was. Each one has its own Disconnect, which doesn't ask, since the same token lets it straight back in. Disconnect all sits by the heading. A long name is cut short, and the whole name, the MCP version and when it connected show on the hint line when you point at it. The heading also says how many are signed in to the page.
• LAST CALLS lists the latest calls with the time, the client and the tool. One that failed has a red "failed" tag.
• On the Mods screen, the Bridge carries the Online tag, like any mod that uses the network. Its Internet tab (a page before 1.5.0) says it listens on 127.0.0.1 (this computer only, incoming), that it answers AI clients' questions about the running game, and that nothing leaves the computer. See Going online.

Console

Command	Does
bridge	off or listening, and the clients connected
bridge on, bridge off	turns it on or off ([Bridge] Enabled)
bridge token new	makes a new token and disconnects every client
bridge disconnect	disconnects every client

The page

The Bridge also serves a page on this computer. It has two views. The code graph draws the game's code as nodes, and Graphs is the editor for mods that do things without any code (Graphs). You open it with Code graph or Graphs editor on the Bridge tab (1.5.0; in 1.4.3 they're called Open page and Graphs), or at a method with the Inspector's Graph buttons. The page has its own sign-in, separate from MCP, and AI clients never see it. [Bridge] OpenPageIn (Open the code graph in on the Mods screen, or "Opens in" on the Bridge tab) picks where it opens: App (a window of its own, CodeGraph.exe, on Windows) or Browser. If App is picked but CodeGraph.exe isn't there, the tab says it opens in the browser, and off Windows it always does. New token, Disconnect all and turning the Bridge off sign the page out too. See Code graph and Graphs.

Not yet

A few things aren't there yet: changing anything from a client, access from other computers, and a relay for clients that can only start a local program (Claude Desktop). The relay will come when someone needs it. (The page itself can save, start and stop graphs, but those three are offered to the page alone, and an AI client never sees them.) Proton hasn't been tried (the Steam Deck runs the game's native Linux build).