MCP guides on Mergeway

Connect Codex over stdio

Mon, 01 Jan 0001 00:00:00 +0000

Connect Codex over stdio

Install mergeway-mcp, validate the repository, and resolve both paths:

command -v mergeway-mcp
cd /path/to/repository
mergeway-cli validate
pwd

Add the local server. Replace both example paths with the absolute values above:

codex mcp add mergeway -- /absolute/path/to/mergeway-mcp \
 --root /absolute/path/to/repository
codex mcp list

Codex CLI and the Codex IDE extension share MCP configuration. The equivalent ~/.codex/config.toml entry is:

[mcp_servers.mergeway]
command = "/absolute/path/to/mergeway-mcp"
args = ["--root", "/absolute/path/to/repository"]

Restart a running client so it reloads configuration. Ask it to list the Mergeway entities, then compare the answer with mergeway-cli entity list. If the server is missing, use codex mcp --help, codex mcp list, and the troubleshooting guide.

Restrict MCP to selected entities

Mon, 01 Jan 0001 00:00:00 +0000

Restrict MCP to selected entities

Choose the minimum exact entity set the task needs. For example, expose users and posts but not comments or tags:

mergeway-mcp --root /absolute/path/to/repository \
 --entity User --entity Post

Put the same repeated arguments in a stdio client’s configuration:

[mcp_servers.mergeway]
command = "/absolute/path/to/mergeway-mcp"
args = [
 "--root", "/absolute/path/to/repository",
 "--entity", "User",
 "--entity", "Post",
]

Restart the client. entity_list should return only Post and User; entity_show for Comment should fail with entity_not_allowed. Names are case-sensitive. Inheritance does not widen the rule: allowing a parent does not allow its descendants.

Serve MCP over HTTP

Mon, 01 Jan 0001 00:00:00 +0000

Serve MCP over HTTP

Prefer stdio for one local client. Use HTTP when a compatible client needs a separately managed streamable endpoint.

Start the loopback-only default:

mergeway-mcp --root /absolute/path/to/repository --transport=http

Configure the client endpoint as http://127.0.0.1:8080/. To avoid a port conflict or mount behind a local proxy:

mergeway-mcp --root /absolute/path/to/repository \
 --transport=http \
 --http-listen 127.0.0.1:9090 \
 --http-base-path /mcp

The endpoint is then http://127.0.0.1:9090/mcp; / and /mcp/anything return 404. Configure --entity at server startup when the client should see less than the whole repository.

Troubleshoot MCP connections and stdout

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshoot MCP connections and stdout

The process exits immediately

Run the configured command directly with the same absolute paths. Diagnostics are on stderr:

/absolute/path/to/mergeway-mcp --root /absolute/path/to/repository --help
/absolute/path/to/mergeway-mcp --root /absolute/path/to/repository < /dev/null

Check that the root exists, contains mergeway.yaml or mergeway.yml directly, and every --entity uses exact case. Exit 2 indicates flags; exit 1 indicates repository or server startup/runtime.

The client reports invalid JSON or loses the stdio connection

Remove wrappers that print banners, shell tracing, progress, or logging to stdout. Stdio reserves stdout for newline-delimited JSON-RPC. Send wrapper diagnostics to stderr. Do not run the server through a formatter or pipe that rewrites stdout.