Skip to content
Back to search

splice-dock

MCP gateway: aggregates MCP servers, HTTP APIs and CLI tools behind one endpoint with per-profile credentials and approvals

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kamilrybacki--splice-dock/badge.svg)](/listings/kamilrybacki--splice-dock)

HTML

<a href="/listings/kamilrybacki--splice-dock"><img src="/api/listings/kamilrybacki--splice-dock/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install Git, Node.js 22, and npm. Use a local machine with ports `8788` and `8789` available. The demo exposes `demo__version`, a read-only tool that prints the gateway’s Node.js version.

git clone https://github.com/kamilrybacki/splice-dock.git splicedock
cd splicedock
npm ci
npm run build

Run the next block from the checkout. It uses a temporary database and stops the gateway when the example finishes. The demo configuration disables strong consent for this local run.

(
  demo_dir="$(mktemp -d)" || exit 1
  export SPLICEDOCK_CONFIG="$PWD/site/examples/quickstart.yaml"
  export SPLICEDOCK_DB_PATH="$demo_dir/splicedock.db"
  export SPLICEDOCK_ADMIN_TOKEN="$(node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))')"

  node dist/main.js > "$demo_dir/gateway.log" 2>&1 &
  gateway_pid=$!
  trap 'kill "$gateway_pid" 2>/dev/null; wait "$gateway_pid" 2>/dev/null; rm -f "$demo_dir"/splicedock.db* "$demo_dir/gateway.log"; rmdir "$demo_dir"' EXIT

  node site/examples/first-call.mjs || { cat "$demo_dir/gateway.log" >&2; exit 1; }
)

The example creates a short-lived profile token, lists tools, calls `demo__version`, and revokes the token. The result should match `node --version`.

<picture> <source media="(prefers-reduced-motion: reduce)" srcset="docs/assets/quickstart-result.svg"> </picture>

To leave the demo running and connect your own client, follow the [Quickstart guide](https://kamilrybacki.github.io/splicedock/start.html) and [issue a profile token](https://kamilrybacki.github.io/splicedock/connect.html#create-token).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 208 lines
  1. <h1 align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="site/assets/splicedock-logo-dark.svg">
  4. <img src="site/assets/splicedock-logo.svg" alt="Splicedock" width="320">
  5. </picture>
  6. </h1>
  7. <p align="center">Connect MCP servers, HTTP APIs, and command-line tools through one MCP endpoint.</p>
  8. <p align="center"><code>v1.0.0</code></p>
  9. <p align="center">
  10. <a href="https://kamilrybacki.github.io/splicedock/start.html"><strong>Quickstart</strong></a> ·
  11. <a href="https://kamilrybacki.github.io/splicedock/tools.html#drivers">Integration examples</a> ·
  12. <a href="https://kamilrybacki.github.io/splicedock/">User guide</a>
  13. </p>
  14. <p align="center">
  15. <img src="docs/assets/cable-divider.svg" width="216" height="18" alt="">
  16. </p>
  17. <details>
  18. <summary>Contents</summary>
  19. - [How it works](#how-it-works)
  20. - [Quickstart](#quickstart)
  21. - [Connect your tools](#connect-your-tools)
  22. - [Run a Code Mode workflow](#run-a-code-mode-workflow)
  23. - [Operate the gateway](#operate-the-gateway)
  24. - [Develop locally](#develop-locally)
  25. </details>
  26. ## <img src="docs/assets/section-flow.svg" width="30" height="24" alt="">How it works
  27. Each Model Context Protocol (MCP) client connects to `/mcp` with a bearer
  28. token. The token selects a profile that determines which tools the client can
  29. discover and call. You manage profiles, credentials, and approvals at the gateway.
  30. ![Request flow from an MCP client through Splicedock to MCP servers, HTTP APIs, and CLI tools](docs/assets/request-flow.svg)
  31. ### Watch an agent call a tool
  32. Ask Codex for the gateway’s Node.js version. It calls `demo__version` through
  33. Splicedock and answers from the result. This replay comes from a local run.
  34. <picture>
  35. <source media="(prefers-reduced-motion: reduce)" srcset="docs/assets/agent-demo.png">
  36. <img src="docs/assets/agent-demo.gif" width="704" alt="Asked which Node.js version Splicedock is running, Codex calls demo__version through Splicedock and reports v22.23.5.">
  37. </picture>
  38. [Read the final frame](docs/assets/agent-demo.png) ·
  39. [Connect your own MCP client](https://kamilrybacki.github.io/splicedock/connect.html)
  40. ## <img src="docs/assets/section-terminal.svg" width="30" height="24" alt="">Quickstart
  41. Install Git, Node.js 22, and npm. Use a local machine with ports `8788` and
  42. `8789` available. The demo exposes `demo__version`, a read-only tool that
  43. prints the gateway’s Node.js version.
  44. ```bash
  45. git clone https://github.com/kamilrybacki/splice-dock.git splicedock
  46. cd splicedock
  47. npm ci
  48. npm run build
  49. ```
  50. Run the next block from the checkout. It uses a temporary database and stops
  51. the gateway when the example finishes. The demo configuration disables strong
  52. consent for this local run.
  53. ```bash
  54. (
  55. demo_dir="$(mktemp -d)" || exit 1
  56. export SPLICEDOCK_CONFIG="$PWD/site/examples/quickstart.yaml"
  57. export SPLICEDOCK_DB_PATH="$demo_dir/splicedock.db"
  58. export SPLICEDOCK_ADMIN_TOKEN="$(node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))')"
  59. node dist/main.js > "$demo_dir/gateway.log" 2>&1 &
  60. gateway_pid=$!
  61. trap 'kill "$gateway_pid" 2>/dev/null; wait "$gateway_pid" 2>/dev/null; rm -f "$demo_dir"/splicedock.db* "$demo_dir/gateway.log"; rmdir "$demo_dir"' EXIT
  62. node site/examples/first-call.mjs || { cat "$demo_dir/gateway.log" >&2; exit 1; }
  63. )
  64. ```
  65. The example creates a short-lived profile token, lists tools, calls
  66. `demo__version`, and revokes the token. The result should match `node --version`.
  67. <picture>
  68. <source media="(prefers-reduced-motion: reduce)" srcset="docs/assets/quickstart-result.svg">
  69. <img src="docs/assets/quickstart-demo.gif" width="704" alt="Local Quickstart recording. The first-call script calls demo__version and returns v22.23.5.">
  70. </picture>
  71. To leave the demo running and connect your own client, follow the
  72. [Quickstart guide](https://kamilrybacki.github.io/splicedock/start.html) and
  73. [issue a profile token](https://kamilrybacki.github.io/splicedock/connect.html#create-token).
  74. ## <img src="docs/assets/section-plug.svg" width="30" height="24" alt="">Connect your tools
  75. Start with the [annotated configuration](splicedock.example.yaml). Add the tool
  76. to the gateway configuration, then add its exposed MCP name to the client’s
  77. [profile manifest](https://kamilrybacki.github.io/splicedock/profiles.html#manifest).
  78. | Driver | Use it to | Example |
  79. | --- | --- | --- |
  80. | `mcp_proxy` | Forward calls to an existing MCP server | [Look up a product with `catalog__lookup_product`](https://kamilrybacki.github.io/splicedock/tools.html#mcp) |
  81. | `http` | Wrap one HTTP API operation as a tool | [Map an argument into a URL with `catalog__product`](https://kamilrybacki.github.io/splicedock/tools.html#http) |
  82. | `cli` | Run a fixed executable with a declared argument template | [Read the Node.js version with `demo__version`](https://kamilrybacki.github.io/splicedock/tools.html#fixed-cli) |
  83. | `cli_passthrough` | Run an allowlisted executable with a caller-supplied argument array | [Allow `git version` and deny `git status` with `git__run`](https://kamilrybacki.github.io/splicedock/tools.html#cli) |
  84. CLI passthrough checks its policy before running the command. A rule can allow
  85. the call, deny it, or require an
  86. [approval](https://kamilrybacki.github.io/splicedock/policies.html#approval).
  87. ![CLI policy decisions after checking the argument array: allow, require approval, or deny](docs/assets/cli-policy.svg)
  88. For backends that need credentials, configure a
  89. [gateway credential binding](https://kamilrybacki.github.io/splicedock/credentials.html)
  90. separately from the client’s profile token.
  91. ## <img src="docs/assets/section-code.svg" width="30" height="24" alt="">Run a Code Mode workflow
  92. The Quickstart profile enables Code Mode. In an MCP client connected to that
  93. profile, send this JavaScript function body as the `code` argument to
  94. `code_mode__execute`.
  95. ```js
  96. const response = await tools.call("demo__version", {});
  97. return { ok: !response.isError, output: response.content };
  98. ```
  99. <details>
  100. <summary>View the full MCP request</summary>
  101. Send this request through an initialized MCP client using the Quickstart profile token.
  102. ```json
  103. {
  104. "jsonrpc": "2.0",
  105. "id": 1,
  106. "method": "tools/call",
  107. "params": {
  108. "name": "code_mode__execute",
  109. "arguments": {
  110. "code": "const response = await tools.call(\"demo__version\", {});\nreturn { ok: !response.isError, output: response.content };"
  111. }
  112. }
  113. }
  114. ```
  115. </details>
  116. The workflow returns the tool result and a call summary. Each call uses the
  117. same profile and policies as a direct MCP call. The JavaScript runs in QuickJS
  118. with tool calls mediated by the gateway. See the
  119. [Code Mode guide](https://kamilrybacki.github.io/splicedock/code-mode.html)
  120. for parallel calls, resource limits, and optional preflight review.
  121. ![One script runs two independent tool calls in parallel and returns a result with a call summary](docs/assets/code-mode-flow.svg)
  122. ### See an agent choose Code Mode
  123. Ask for the gateway’s OS, Node.js version, and Git version over a slow link.
  124. Codex can call each tool directly. In this local run it chose Code Mode,
  125. listed the available tools, and then ran the three reads in parallel.
  126. <picture>
  127. <source media="(prefers-reduced-motion: reduce)" srcset="docs/assets/code-mode-agent-demo.png">
  128. <img src="docs/assets/code-mode-agent-demo.gif" width="704" alt="Codex chooses Code Mode, lists the tools, and uses Promise.all to read the OS, Node.js version, and Git version. All three calls succeed.">
  129. </picture>
  130. [Read the final frame](docs/assets/code-mode-agent-demo.png)
  131. ## <img src="docs/assets/section-controls.svg" width="30" height="24" alt="">Operate the gateway
  132. - **Access.** Require profile tokens with `server.require_profile_token: true`.
  133. [Create, rotate, or revoke a token](https://kamilrybacki.github.io/splicedock/connect.html).
  134. - **Admin UI.** Manage profile YAML, review approvals, and inspect the audit log.
  135. The admin listener defaults to port `8789` and exposes Prometheus metrics
  136. at `/metrics`. [Admin UI and observability](https://kamilrybacki.github.io/splicedock/webui.html).
  137. - **Storage.** Run a single replica with SQLite or use shared PostgreSQL for
  138. multiple replicas. [Storage configuration and migration](docs/operations.md#storage-backend).
  139. - **Approvals.** Review [learned grants and phone approvals](docs/operations.md)
  140. before enabling them. See the [hardening runbooks](docs/hardening/) for deployment details.
  141. ## <img src="docs/assets/section-build.svg" width="30" height="24" alt="">Develop locally
  142. | Task | Command |
  143. | --- | --- |
  144. | Run with file watching | `npm run dev` |
  145. | Compile TypeScript | `npm run build` |
  146. | Start the compiled gateway | `npm start` |
  147. | Lint | `npm run lint` |
  148. | Run tests | `npm test` |
  149. | Run one test suite | `npm run test:unit`, `npm run test:integration`, or `npm run test:e2e` |
  150. | Build and check the docs | `npm run docs:build && npm run docs:check` |
  151. Gateway code lives in [`src/`](src/), tests in [`tests/`](tests/), and the
  152. public user guide in [`site/`](site/). The
  153. [architecture decisions](docs/adrs/), [token and metrics authentication](docs/profile-token-and-metrics-auth.md),
  154. and [admin identity and CSRF](docs/admin-identity-and-csrf.md) notes document the design.
  155. Check the [CI runs](https://github.com/kamilrybacki/splice-dock/actions/workflows/ci.yml) for build and test results.
  156. See [CONTRIBUTING.md](CONTRIBUTING.md) for how pull requests and releases work.
  157. ## License
  158. [MIT](LICENSE). Report security problems privately, as described in [SECURITY.md](SECURITY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.