# Seam — Setup Guide for AI Agents

This file is written for AI agents (coding assistants and autonomous agents) helping a developer
integrate Seam. Follow the steps in order. Everything here is safe to execute in a development
environment unless noted.

## What is Seam

Seam (https://www.seam.co) is a unified API for access control and smart devices: smart locks,
access control systems (ACS), thermostats, noise sensors, and cameras from 39+ manufacturers
(Yale, Schlage, August, Salto, Brivo, ASSA ABLOY, Nuki, Igloohome, and more). One API surface
covers device control, access codes, mobile keys, credentials, events, and webhooks.

Key concepts:

- **Workspace** — an isolated environment holding connected accounts and devices. Use a
  production workspace to work with the user's real devices.
- **Connected account** — a device-provider account (e.g. a Yale account) linked to Seam,
  usually via a Connect Webview the end user completes.
- **Access grant** — the recommended way to give a person access to a space. `POST
  /access_grants/create` works for BOTH standalone smart locks (via `device_ids`) and ACS
  (via `acs_entrance_ids` or `space_ids`). Prefer it over the low-level `access_codes` and
  `acs` APIs.
- **Action attempt** — async tracker returned by actions like unlock; poll it for completion.

## Step 1 — Install the Seam plugin

The Seam plugin gives you Seam-specific skills (seam-access-grants, seam-access-codes,
seam-reservation-automations) plus the Seam docs MCP server.

Works with most agents (Claude Code, Cursor, Codex, Copilot, Gemini CLI):

    npx skills add seamapi/seam-plugin

Claude Code alternative (run as slash commands, not shell):

    /plugin marketplace add seamapi/seam-plugin
    /plugin install seam@seamapi

Source: https://github.com/seamapi/seam-plugin

## Step 2 — Install the Seam CLI

The Seam CLI lets you and your user run Seam API calls from the terminal.

    npm install -g @seamapi/cli

Source: https://github.com/seamapi/seam-cli

## Step 3 — Connect the Seam MCP server (if you cannot install the plugin)

Server URL (Streamable HTTP, `/mcp` path required): `https://mcp.seam.co/mcp`

The docs tier requires no API key or account. It exposes docs/device-database search
(`search_docs`, `get_doc`, `list_doc_sections`), the full API map (`api_overview`,
`api_search`), provider context packs (`list_context_packs`, `get_context_pack`), and
runnable example apps (`list_example_apps`, `get_example_app`). With an authenticated
workspace it can also run real API calls (`api_execute`) and inspect live devices and events.

Example client registration:

    claude mcp add --transport http seam https://mcp.seam.co/mcp
    codex mcp add seam --url https://mcp.seam.co/mcp

## Step 4 — Activation steps

1. Ask your user to create a Seam account: https://console.seam.co/signup
2. Have them create an API key in the Seam Console, in a **production workspace**.
3. Store the key as `SEAM_API_KEY` in `.env`. Never commit it; add `.env` to `.gitignore`.
   Never ask the user for their Seam password.
4. Install the SDK for the project's language:
   - JavaScript/TypeScript: `npm install seam`
   - Python: `pip install seam`
5. Verify the connection by listing devices. A new workspace starts empty — have the user
   connect their device account via a Connect Webview first, then list again.

## Recommended integration path

1. Use the skills installed by the Seam plugin (seam-access-grants, seam-access-codes,
   seam-reservation-automations) and follow their connect + access-grant guidance.
2. Use **access grants** to grant access; use webhooks for event-driven flows
   (e.g. `lock.locked`, `access_code.created`).
3. For reference implementations, fetch an example app (`list_example_apps`): Express or
   Next.js App Router, in `full_api` mode (your own UI on the Seam API) or `customer_portal`
   mode (embed Seam's hosted portal with ~2 endpoints).

## More resources

- Documentation: https://docs.seam.co
- MCP installation guide: https://docs.seam.co/api/mcp-installation
- Supported devices and systems: https://www.seam.co/supported-devices-and-systems
- Support: support@seam.co