MCP Forge

View Markdown

MCP Forge quickstart.mdDownload .md

# MCP Forge quickstart

Go from an empty machine to one governed MCP endpoint. The guided installer is
the shortest supported path: it verifies the published binary, creates a
commented bootstrap configuration, tests the first source, initializes
authentication and registers an automatically restarted background service.

In `v1`, supported sources are PostgreSQL, MySQL and SQL Server databases.
Agents receive typed tools governed by policy; they never receive a raw SQL
interface.

## Run the guided installer

### Linux and macOS

The safer path downloads the versioned script so you can inspect it first:

```bash
# Download the versioned v1 installer entrypoint.
curl --fail --location --output runku-install.sh \
  https://runku.dev/install/v1/install.sh
# Review it, then run it from an interactive terminal.
less runku-install.sh
sh runku-install.sh
```

From a trusted terminal, the equivalent one-line command is:

```bash
# Prompts are read from the terminal even though the script arrives by pipe.
curl --fail --location https://runku.dev/install/v1/install.sh | sh
```

### Windows

Open PowerShell as Administrator. Downloading first makes the script easy to
review:

```powershell
# Download and inspect the versioned PowerShell installer.
Invoke-WebRequest https://runku.dev/install/v1/install.ps1 -OutFile runku-install.ps1
Get-Content .\runku-install.ps1
# Bypass applies only to this process; it does not change machine policy.
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\runku-install.ps1
```

From a trusted elevated PowerShell session, the one-line equivalent is:

```powershell
# Execute the v1 installer in the current elevated session.
Invoke-RestMethod https://runku.dev/install/v1/install.ps1 | Invoke-Expression
```

[Download for Linux/macOS](https://runku.dev/install/v1/install.sh) or
[download for Windows](https://runku.dev/install/v1/install.ps1).

## What the wizard asks

Have these values ready:

| Step | Required information | Why Runku needs it |
|---|---|---|
| Listener | Local HTTP port, default `8080` | Serves the portal and connector endpoints |
| Admin store | Dedicated PostgreSQL DSN or SQLite | Stores Runku policy, identities and API-key hashes |
| First connector | ID, engine and source DSN | Identifies and connects the source published through MCP |
| Authentication | API key, Google, Entra or Keycloak/OIDC | Verifies portal and MCP callers |

The admin store and connector are separate security boundaries. Even when both
use PostgreSQL, use different databases and credentials: `store` is private
Runku state; `connectors[]` points to business data governed by Runku.

The installer tests connectivity and schema introspection before completing.
For API-key authentication, it prints one initial token and will not start the
service until you confirm that token has been saved securely. With OIDC, users
sign in through the configured provider and no bootstrap API key is generated.

## What the installer changes

| Platform | Binary | Configuration and data | Managed process |
|---|---|---|---|
| Linux | `/usr/local/bin/runku` | `/etc/runku`, `/var/lib/runku` | `systemd` unit `runku.service` |
| macOS | `/usr/local/bin/runku` | `/etc/runku`, `/var/lib/runku` | `launchd` daemon `dev.runku.mcp` |
| Windows | `C:\Program Files\Runku` | `C:\ProgramData\Runku` | Startup task `Runku MCP Forge` running as `SYSTEM` |

Connector and store secrets are written with restricted permissions and passed
to the service through its environment. The generated `config.yaml` contains
environment references, not plaintext DSNs.

## Verify the result

The final screen prints the actual URLs chosen during setup. With the default
port and connector ID they are:

- Portal: `http://localhost:8080/portal/`
- MCP endpoint: `http://localhost:8080/mcp/primary`

Check the managed process:

```bash
# Linux: current state and recent startup errors.
sudo systemctl status runku --no-pager
sudo journalctl -u runku -n 100 --no-pager

# macOS: current launchd state and the configured log files.
sudo launchctl print system/dev.runku.mcp
tail -n 100 /var/lib/runku/runku-error.log
```

```powershell
# Windows: task state and the listening process.
Get-ScheduledTask -TaskName "Runku MCP Forge"
Get-NetTCPConnection -LocalPort 8080 -State Listen
```

## Publish the first safe tools

Installation connects and introspects the source, but deliberately exposes no
tables or writes on your behalf. Open the local portal and:

1. Select the connector.
2. Explicitly expose the required tables and columns.
3. Mask sensitive columns before publishing tools.
4. Keep mutations disabled unless an operation genuinely needs them.
5. Test one allowed and one blocked call in the playground.

Only then point an MCP client at the connector URL. Continue with
[policy and masking](/docs/v1/mcp-policy) and
[authentication and permissions](/docs/v1/mcp-auth-permissions).

For controlled deployments, custom filesystem layouts, Compose, manual service
registration, upgrades and rollback, use the
[complete manual installation guide](/docs/v1/mcp-installation).

MCP Forge quickstart

Go from an empty machine to one governed MCP endpoint. The guided installer is the shortest supported path: it verifies the published binary, creates a commented bootstrap configuration, tests the first source, initializes authentication and registers an automatically restarted background service.

In v1, supported sources are PostgreSQL, MySQL and SQL Server databases. Agents receive typed tools governed by policy; they never receive a raw SQL interface.

Run the guided installer

Linux and macOS

The safer path downloads the versioned script so you can inspect it first:

# Download the versioned v1 installer entrypoint.
curl --fail --location --output runku-install.sh \
  https://runku.dev/install/v1/install.sh
# Review it, then run it from an interactive terminal.
less runku-install.sh
sh runku-install.sh

From a trusted terminal, the equivalent one-line command is:

# Prompts are read from the terminal even though the script arrives by pipe.
curl --fail --location https://runku.dev/install/v1/install.sh | sh

Windows

Open PowerShell as Administrator. Downloading first makes the script easy to review:

# Download and inspect the versioned PowerShell installer.
Invoke-WebRequest https://runku.dev/install/v1/install.ps1 -OutFile runku-install.ps1
Get-Content .\runku-install.ps1
# Bypass applies only to this process; it does not change machine policy.
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\runku-install.ps1

From a trusted elevated PowerShell session, the one-line equivalent is:

# Execute the v1 installer in the current elevated session.
Invoke-RestMethod https://runku.dev/install/v1/install.ps1 | Invoke-Expression

Download for Linux/macOS or download for Windows.

What the wizard asks

Have these values ready:

Step	Required information	Why Runku needs it
Listener	Local HTTP port, default `8080`	Serves the portal and connector endpoints
Admin store	Dedicated PostgreSQL DSN or SQLite	Stores Runku policy, identities and API-key hashes
First connector	ID, engine and source DSN	Identifies and connects the source published through MCP
Authentication	API key, Google, Entra or Keycloak/OIDC	Verifies portal and MCP callers

The admin store and connector are separate security boundaries. Even when both use PostgreSQL, use different databases and credentials: store is private Runku state; connectors[] points to business data governed by Runku.

The installer tests connectivity and schema introspection before completing. For API-key authentication, it prints one initial token and will not start the service until you confirm that token has been saved securely. With OIDC, users sign in through the configured provider and no bootstrap API key is generated.

What the installer changes

Platform	Binary	Configuration and data	Managed process
Linux	`/usr/local/bin/runku`	`/etc/runku`, `/var/lib/runku`	`systemd` unit `runku.service`
macOS	`/usr/local/bin/runku`	`/etc/runku`, `/var/lib/runku`	`launchd` daemon `dev.runku.mcp`
Windows	`C:\Program Files\Runku`	`C:\ProgramData\Runku`	Startup task `Runku MCP Forge` running as `SYSTEM`

Connector and store secrets are written with restricted permissions and passed to the service through its environment. The generated config.yaml contains environment references, not plaintext DSNs.

Verify the result

The final screen prints the actual URLs chosen during setup. With the default port and connector ID they are:

Portal: http://localhost:8080/portal/
MCP endpoint: http://localhost:8080/mcp/primary

Check the managed process:

# Linux: current state and recent startup errors.
sudo systemctl status runku --no-pager
sudo journalctl -u runku -n 100 --no-pager

# macOS: current launchd state and the configured log files.
sudo launchctl print system/dev.runku.mcp
tail -n 100 /var/lib/runku/runku-error.log

# Windows: task state and the listening process.
Get-ScheduledTask -TaskName "Runku MCP Forge"
Get-NetTCPConnection -LocalPort 8080 -State Listen

Publish the first safe tools

Installation connects and introspects the source, but deliberately exposes no tables or writes on your behalf. Open the local portal and:

Select the connector.
Explicitly expose the required tables and columns.
Mask sensitive columns before publishing tools.
Keep mutations disabled unless an operation genuinely needs them.
Test one allowed and one blocked call in the playground.

Only then point an MCP client at the connector URL. Continue with policy and masking and authentication and permissions.

For controlled deployments, custom filesystem layouts, Compose, manual service registration, upgrades and rollback, use the complete manual installation guide.