# External Connections

## Credential-backed connections

Users configure connections via `/connect`. Credentials are stored in the OS keychain — you cannot read them directly. Connection metadata (names, field names) is stored in `settings.json`.

`/connect` provides an interactive menu:

- **Add connection**: create a new connection with named fields (values go to OS keychain)
- **Manage existing**: view fields, keychain status, or remove a connection
- **Open config**: open `settings.json` in the default editor to view/edit connection metadata directly

Pass the connection name in the bash tool's `connections` parameter. Credentials are injected as env vars into that subprocess only.

```json
{ "command": "python3 -c '...'", "connections": ["snowflake-prod"] }
```

**Env var naming**: Field names are used directly as env var keys. Name fields to match what the target tool expects (e.g. `GITHUB_TOKEN`, `DATABASE_URL`).

Connection-backed execution requires explicit user approval every time (no "accept all"). If no connection is configured, tell the user to run `/connect`.

## MCP integration

Connections also power MCP servers. Instead of hardcoding secrets in `mcp.json`, reference a connection by name:

```json
{
  "mcpServers": {
    "github": {
      "command": "pnpm",
      "args": ["dlx", "@modelcontextprotocol/server-github"],
      "connection": "github"
    }
  }
}
```

The connection's fields are injected as env vars into the MCP server process at startup. Field names must match the env vars the MCP server expects (e.g. a connection with a `GITHUB_TOKEN` field → the server sees `$GITHUB_TOKEN`).

## Pip packages

| Type | Package | Notes |
|------|---------|-------|
| Snowflake | `snowflake-connector-python` | Account format: `xy12345.us-east-1` |
| PostgreSQL | `psycopg2-binary` | sslmode default `prefer`, prod often needs `require` |
| Oracle | `oracledb` | Thin mode, no Oracle Client needed. DSN: `host:port/service` |
| MySQL | `mysql-connector-python` | |
| Salesforce | `simple-salesforce` | security_token may be required depending on org |
| Notion / HubSpot / Slack / Airtable / Workday / SAP | `requests` | REST APIs with bearer token or basic auth |

Install drivers in a separate bash call (without `connections`), then use the connection:

```json
{ "command": "pip install psycopg2-binary" }
```

## Airtable

For Airtable setup and usage guidance, read:

- `skills/connections/airtable.md`

## Cloud drives (no connection needed)

These sync to the local filesystem. Use standard file tools — no API, no auth, no `connections` parameter.

### Windows

| Service | Paths |
|---------|-------|
| OneDrive | `%USERPROFILE%\OneDrive`, `%USERPROFILE%\OneDrive - <Company>` |
| SharePoint | Synced via OneDrive: `%USERPROFILE%\<Company>\<Site> - Documents` |
| Google Drive | `G:\My Drive` (Drive for Desktop mount) |
| Box | `%USERPROFILE%\Box` or `B:\` (Box Drive mount) |
| Dropbox | `%USERPROFILE%\Dropbox` (or read `%USERPROFILE%\.dropbox\info.json`) |

### macOS

| Service | Paths |
|---------|-------|
| OneDrive | `~/Library/CloudStorage/OneDrive-*` |
| SharePoint | `~/Library/CloudStorage/OneDrive-*SharePoint*` |
| Google Drive | `~/Library/CloudStorage/GoogleDrive-*` |
| Box | `~/Library/CloudStorage/Box-*` or `~/Box` |
| Dropbox | `~/Library/CloudStorage/Dropbox` or `~/Dropbox` |

**Gotchas**: Files On-Demand (Windows) may show placeholders — reading triggers download. Always quote paths (spaces in folder names). SharePoint IS OneDrive — no separate sync client.
