> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marina.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Connect your business systems to Marina once, then let apps read them with explicit approval.

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

1. Open **Settings → Connections → Add connection** and pick a connector.
2. 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.
3. 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](/connections/overview).

## 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](/guides/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:

```json marina.json theme={null}
{
  "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:

```ts theme={null}
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:

```ts theme={null}
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](/guides/local-development).

<Card title="Connector catalog" icon="library" href="/connectors/index">
  Every supported service, with setup and operations per connector.
</Card>

<Card title="Automate connection setup" icon="braces" href="/reference/api">
  Create, verify, and activate connections with the Marina API.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.