# Using connectable.sh

connectable.sh is an MCP gateway: one MCP endpoint in front of MCP servers, REST/GraphQL APIs, databases, buckets, web pages and local coding agents, with per-tool policy, rate limits, approvals and an audit log.

## Install

```bash
npm install -g connectable.sh
# or
bun add -g connectable.sh
```

## The smallest working setup

A `connectors.json` with a SQLite database and a folder of files (`examples/support-desk` in the repo):

```json
{
	"connectors": [
		{
			"name": "support",
			"transport": "driver",
			"driver": "sqlite",
			"options": {
				"path": "./support.db",
				"maxRows": 100,
				"instructions": "tickets.status is one of open, pending, closed. Join tickets.customer_id to customers.id for the plan."
			}
		},
		{
			"name": "guides",
			"transport": "driver",
			"driver": "filesystem",
			"options": { "roots": ["./guides"] }
		}
	]
}
```

Validate it, dial it, then point a client at the gateway:

```
$ connectable check connectors.json
✓ connectors.json is valid — 2 connector(s)
  support (driver)
  guides (driver)
$ connectable probe connectors.json
✓ support — 3 tool(s), 1ms
✓ guides — 4 tool(s), 1ms
``` In a second terminal:

```bash
bun client.ts                                  # default http://localhost:3333/mcp
```

```bash
claude mcp add --transport http support-desk http://localhost:3333/mcp
```

Tools arrive namespaced `<connector>__<tool>`, such as `support__query`.

## Connector options

| Field | Applies to | What it does |
| --- | --- | --- |
| `name` | all | Namespace for the connector's tools: `name__tool` |
| `transport` | all | `stdio`, `http`, `openapi`, `graphql`, `web` or `driver` |
| `include` | `openapi`, `graphql` | Operations to serve as tools. No default: omitted means zero tools |
| `headers`, `auth` | `http`, `openapi`, `graphql` | Fixed headers, or an OAuth2 client-credentials / hook block for short-lived tokens |
| `pages` | `web` | Pages to serve as read-only tools; `selector` narrows the extracted Markdown |
| `driver`, `options` | `driver` | `postgres`, `mysql`, `sqlite`, `duckdb`, `duckdb-s3`, `s3`, `filesystem`, `agent` and its options |
| `options.maxRows` | SQL drivers | Row cap per query, reported when hit |
| `options.allowWrites` | SQL drivers | Adds the `execute` tool. Off by default |
| `options.instructions` | SQL, S3, filesystem | Appended to that connector's tool descriptions |
| `instructions` (top level) | the file | Sent as the server's `instructions` at `initialize` |

Credentials: `{{ env.NAME }}` in a self-hosted file, `{{ secrets.NAME }}` on a hosted deployment. Never put a value in a hosted connector.

## Mistakes that break it

1. Leaving out `include` on an `openapi` or `graphql` connector. It has no default, so the connector serves zero tools.
2. Adding a `stdio` connector to a hosted deployment. It is refused; serve it from the machine it runs on through a Link (`connectable link pair`).
3. Expecting an instructions or playbook edit to reach an open session. They are sent at `initialize`, so only new sessions see the change.

## More

- https://connectable.sh/reference: every option, route and variable
- https://connectable.sh/guide: end-to-end walkthroughs
- https://connectable.sh/llms.txt