Connections

Each connection is a directory in connections/ containing a spec, access rules, and optional documentation. Pre-built plugins come with everything maintained — you just provide credentials.

amodal pkg connect slack          # install a plugin
amodal pkg sync --from <url>      # sync from OpenAPI/GraphQL

Directory Structure

connections/my-api/
├── spec.json       ← API source, auth, entities, sync config
├── access.json     ← field restrictions, action tiers, row scoping
├── surface.md      ← (optional) endpoint documentation
├── entities.md     ← (optional) entity definitions
└── rules.md        ← (optional) business rules

spec.json

Connections support two protocols: REST (the default) for HTTP APIs, and MCP for Model Context Protocol tool servers.

REST Connection

{
  "baseUrl": "https://api.example.com",
  "specUrl": "https://api.example.com/openapi.json",
  "format": "openapi",
  "auth": {
    "type": "bearer",
    "token": "env:MY_API_TOKEN",
    "header": "Authorization",
    "prefix": "Bearer "
  },
  "sync": {
    "auto": true,
    "frequency": "on_push",
    "notify_drift": true
  },
  "filter": {
    "tags": ["public"],
    "include_paths": ["/api/v2/**"],
    "exclude_paths": ["/api/v2/internal/**"]
  }
}

MCP Connection

{
  "protocol": "mcp",
  "transport": "stdio",
  "command": "uvx",
  "args": ["mcp-server-github"],
  "env": { "GITHUB_TOKEN": "env:GITHUB_TOKEN" }
}

MCP connections do not require access.json, baseUrl, or format. See MCP Servers for full details on transports and configuration.

Fields

Field	Description
`protocol`	`"rest"` (default) or `"mcp"`
`baseUrl`	API base URL (required for REST)
`specUrl`	URL to the API spec document (optional)
`testPath`	Relative path appended to baseUrl for `validate` health checks (optional, e.g. `"/me"`)
`format`	`"openapi"`, `"graphql"`, `"grpc"`, `"rest"`, or `"aws-api"` (REST only)
`auth.type`	`"bearer"`, `"api_key"`, `"oauth2"`, `"basic"`, `"header"` (REST only)
`sync`	Auto-sync settings and drift notification (REST only)
`filter`	Include/exclude endpoints by tag or path glob (REST only)
`transport`	`"stdio"`, `"sse"`, or `"http"` (MCP only)
`command`	Command to spawn (MCP stdio only)
`args`	Command arguments (MCP stdio only)
`env`	Environment variables (MCP stdio only)
`url`	Server URL (MCP sse/http only)
`headers`	HTTP headers, e.g. for auth (MCP sse/http only)
`trust`	Trust unsigned responses (MCP http only)

access.json

Controls what the agent can see and do:

{
  "endpoints": {
    "GET /api/deals/{id}": {
      "returns": ["Deal"],
      "confirm": false
    },
    "POST /api/deals": {
      "returns": ["Deal"],
      "confirm": true,
      "reason": "Creates a new deal",
      "thresholds": [
        { "field": "body.amount", "above": 10000, "escalate": "review" }
      ]
    },
    "DELETE /api/deals/{id}": {
      "returns": ["Deal"],
      "confirm": "never",
      "reason": "Deletion not allowed via agent"
    }
  },
  "fieldRestrictions": [
    {
      "entity": "Contact",
      "field": "ssn",
      "policy": "never_retrieve",
      "sensitivity": "pii_identifier",
      "reason": "PII — never exposed"
    },
    {
      "entity": "Contact",
      "field": "email",
      "policy": "retrieve_but_redact",
      "sensitivity": "pii_name"
    },
    {
      "entity": "Deal",
      "field": "internal_notes",
      "policy": "role_gated",
      "sensitivity": "internal",
      "allowedRoles": ["supervisor"]
    }
  ],
  "rowScoping": {
    "Deal": {
      "owner_id": {
        "type": "field_match",
        "userContextField": "userId",
        "label": "your deals"
      }
    }
  },
  "delegations": {
    "enabled": true,
    "maxDurationDays": 7,
    "escalateConfirm": true
  },
  "alternativeLookups": [
    {
      "restrictedField": "Contact.ssn",
      "alternativeEndpoint": "GET /api/contacts/{id}/verification-status",
      "description": "Use verification status instead of raw SSN"
    }
  ]
}

Action Tiers

Tier	Behavior
`false` / omitted	Allow without confirmation
`true` / `"confirm"`	Ask user for approval before executing
`"review"`	Show the full plan before executing
`"never"`	Block the operation entirely

Field Restriction Policies

Policy	Effect
`never_retrieve`	Field completely removed from API responses
`retrieve_but_redact`	Kept in data, replaced with `[REDACTED]` in output
`role_gated`	Removed if user lacks `allowedRoles`, else redactable

Threshold Escalation

Endpoints can escalate their confirmation tier based on request parameters:

{ "field": "body.amount", "above": 10000, "escalate": "review" }

If body.amount > 10000, the tier escalates from confirm to review.

Drift Detection

amodal pkg sync --check    # report drift without updating (CI-friendly)
amodal pkg sync            # update local specs from remote

Pre-built Plugins

50+ pre-built connection plugins are available for popular APIs like Slack, GitHub, Stripe, Datadog, Jira, and more. Browse and install them from the Amodal Marketplace, or install directly from the CLI:

amodal pkg connect slack
amodal pkg connect stripe
amodal pkg connect datadog

For APIs not in the marketplace, create custom connections using the directory structure above with your own OpenAPI or GraphQL spec.