Overview

A connection is an external service (a Shopify store, a Mercury account, a Postgres database, an MCP server) configured once under Settings → Connections. Apps then read from it through Marina: credentials stay in Marina’s encrypted vault and are never exposed to app code, and every call is checked and recorded.

Connect a service

Open Settings → Connections → Add connection and pick a connector.
Fill in the configuration and paste the credential the dialog asks for. Each dialog explains where to create the credential on the provider’s side.
Save. Marina verifies the connection with a read-only test call and activates it.

Every connection has an immutable connection id, unique per connector in the workspace (for example mercury/evident). Display names stay editable; the id is what apps reference.

What apps can do with a connection

All connection operations available to apps are read-only. Several connectors additionally require an explicit allowlist, configured on the connection:

Connector	Allowlist
Slack	Channel IDs apps may read.
Remote MCP	Tool names apps may call. Marina also requires each tool to declare itself read-only.
OpenAPI	Operation IDs apps may call. Marina also requires each to be a GET.

An app must additionally declare, per version, exactly which connections and operations it uses; see Using connections in apps.

Organization and per-person connections

Most connections hold one credential for the whole organization. Some connectors also support per-person connections: the admin creates the connection with “Each person connects their own account”, and each member adds their own credential under Settings → Your connections. Calls then run on the credential of whoever is using the app, so two people can see different data. Remote MCP supports this mode.

Dev access

During local development, connection calls run as the developer. Admins can use every organization connection this way; other members need dev access, granted per connection under Settings → Connections → Dev access. Per-person connections need no grant: the developer’s own credential is the authority.

Using connections in apps

An app names the exact connections it uses in marina.json, with the operations it may run on each. The connection id is always explicit:

marina.json

{
  "schema": 1,
  "entrypoint": "src/app.ts",
  "connections": {
    "shopify": [{ "connection": "sleep_karma", "capabilities": ["orders.list", "inventory.list"] }],
    "mercury": [
      { "connection": "evident", "capabilities": ["accounts.list", "transactions.list"] },
      { "connection": "sleep_karma", "capabilities": ["transactions.list"] }
    ]
  }
}

Deploying validates every declaration: the connection must exist and every operation must exist in the connector’s catalog and be read-only. New connections or operations appear in the version’s approval as concrete effects, such as “Let this app read mercury/sleep_karma: transactions.list”, and the approved list is that version’s fixed authority. App code cannot call anything outside it. Each connection’s id and its available operations are shown on its row under Settings → Connections.

Calling operations

Address the connector kind. When the app declares exactly one connection of that kind, nothing else is needed:

const orders = await marina.connections.shopify.orders.list({
  query: "financial_status:paid",
});

When the app declares several connections of one kind, name the one you mean with the reserved connection field:

const transactions = await marina.connections.mercury.transactions.list({
  connection: "sleep_karma",
  start: "2026-08-01",
});

List operations return { items, cursor }; pass the returned cursor back to continue. Inputs are validated against the operation’s schema before any provider call.

Per-person connections in apps

When a declared connection is per-person, each call uses the credential of the person using the app. Someone who has not connected their account gets an error telling them to connect it first, under Settings → Your connections. Background jobs cannot call per-person connections, because a job has no person to connect as.

Local development

marina dev bridges these calls to Marina under your own access, so you develop against live data without credentials on your machine. See local development.

Connector catalog

Every supported service, with setup and operations per connector.

Automate connection setup

Create, verify, and activate connections with the Marina API.

Get started

Guides

Platform services

Connections

Reference

Connect a service

What apps can do with a connection

Organization and per-person connections

Dev access

Using connections in apps

Calling operations

Per-person connections in apps

Local development

Connector catalog

Automate connection setup

​Connect a service

​What apps can do with a connection

​Organization and per-person connections

​Dev access

​Using connections in apps

​Calling operations

​Per-person connections in apps

​Local development

Connector catalog

Automate connection setup

Connect a service

What apps can do with a connection

Organization and per-person connections

Dev access

Using connections in apps

Calling operations

Per-person connections in apps

Local development