Summer API, CLI and MCP

Summer has its own API, command-line tool (CLI) and MCP server for company setup and case work. They are separate from your company's own systems: you never give Summer your users' passwords, and an agent never needs another company's credentials to use Summer. All three use the same Summer accounts, permissions and records as the workspace.

Availability: the developer platform is turned on per Summer deployment. If https://api.gosummer.ai/v1 answers developer_platform_disabled, it is not available to your workspace yet. The @gosummer/cli package below is the planned release name; until it is published, Summer support provides the CLI release for early access.

Connect an agent or terminal#

Install the CLI with Node.js 22 or newer and sign in:

npx --yes @gosummer/cli@0.1.0 login --scope setup --json

Summer opens the consent page in your browser. Sign in with your Summer account, choose the companies, environments and permissions, and select Allow. The CLI stores its credential in your operating system's credential store. It never writes it to a plain file.

• summer whoami --json shows your access status and this connection's grant.
• summer logout revokes the connection.
• Your account → Security → Agent connections lists every connection, with its last use, and lets you revoke it.

A person whose Summer access is still awaiting approval can connect, read their status and submit an access request (summer access request). Company access appears after the Summer team approves the account. Accepting an invitation does not change an existing connection; sign in again to add the company.

For a headless job, supply a short-lived token from your secret manager in SUMMER_ACCESS_TOKEN, or use a service account (below).

Permissions#

Every request rechecks your current Summer approval, company membership and role. Removing a person from a company removes that company from their connections at once.

These are never available to an agent, whatever it is granted: approving a business action, outgoing customer message or plan; revealing a saved credential; approving Summer access requests; ownership transfer and owner or admin role changes; raising spending limits; identity attestations and clinical directions.

Company and environment ownership#

Company settings, team membership and company knowledge are company-wide. An edit through the API affects every environment, including production, and the API says so in its response. Credentials, Messenger installations, cases and events belong to one environment. A connection only reaches the environments selected when it was approved, and a deployment only serves Messenger and cases for the environment it runs.

States#

Results report each item as one of:

• saved: stored in Summer. Not a provider check.
• verified: a supported live check passed for the current configuration.
• pending: waiting for a person, a missing field or a missing permission.
• unavailable: not possible here, with a reason such as missing_scope, environment_not_served, operational_connection_pending or human_required.
• enabled / disabled: a live setting.
• unsupported: Summer cannot check this yet. It has not passed.

Set up from a project#

Describe what your project needs in summer.setup.json. It holds no secret values:

{
  "version": 1,
  "company": "YOUR_COMPANY_ID",
  "environment": "staging",
  "messenger": { "installations": [{
    "key": "website",
    "signing_key_destination": ".env.local:SUMMER_MESSENGER_SIGNING_KEY",
    "settings": { "enabled": true, "guests_enabled": true, "display_name": "Support",
      "allowed_origins": ["http://localhost:3000"], "privacy_url": "", "fallback_url": "", "office_hours": "" }
  }] },
  "credentials": [{ "name": "STRIPE_READ_KEY", "from_env": "STRIPE_READ_KEY" }],
  "knowledge": [{ "id": "ops.company-profile", "file": "summer/company-profile.md", "reason": "Initial setup" }]
}

Then plan and apply:

summer setup plan --file summer.setup.json --out summer.plan.json --json
summer setup apply --plan summer.plan.json --file summer.setup.json --json

The plan compares the file with Summer and lists only the changes, with the versions it expects. Existing installations and credentials are kept; a credential is replaced only with "replace": true and the replacement permission. Applying a plan again after an interruption replays finished steps instead of repeating them. If someone changed a resource after planning, that step reports stale: plan again. If a step's outcome is unknown, it reports uncertain with the safe next step.

Each apply writes a receipt to .summer/receipts/PLAN_ID.json. It names what changed and holds no secret values. To undo that run, use summer setup rollback --receipt .summer/receipts/PLAN_ID.json. Rollback restores knowledge and installation settings only where nobody changed them afterwards, turns off (rather than deletes) an installation it created, removes a credential it created when the connection has the replacement permission, and reports a replaced credential as manual because Summer never keeps old values.

The CLI reads each credential from the environment variable you name and sends it directly to Summer. It writes a new Messenger signing key straight to the file you choose and refuses files that Git tracks or does not ignore. Neither value is printed. Use summer messenger check --url http://localhost:3000/ --installation ID to check your page's embed and Content-Security-Policy. summer verify runs harmless live reads for Stripe, Intercom and EasyPost credentials: it reports the account the key reaches and flags a live key saved for staging (or a test key for production). Confirm that the account is the one you expect. Other providers are reported as not checked.

API#

• Base URL: https://api.gosummer.ai/v1. The OpenAPI description is at /v1/openapi.json.
• Authentication: OAuth 2.1 bearer tokens from Summer (authorization code with PKCE, or client credentials for service accounts). Tokens for the API do not work on the MCP server, and the reverse.
• Writes that create work or move a secret need an Idempotency-Key header. Reusing a key returns the original result; a key reused for a different request is refused.
• Updates take the version you expect (expected_version or revision). A stale version returns version_conflict without changing anything.
• Requests that issue a one-time secret need Summer-One-Time-Secret: accept. Write the returned value straight to a secret store. A replayed response does not contain it again; rotate if it was lost.
• Errors are {"error": {"code", "message", "retryable", "details"}, "request_id"}. A refusal from Summer's operations backend carries details.definite: true when nothing was changed.
• Requests are rate limited per connection, and the sign-in endpoints per address. A 429 response includes Retry-After.

MCP#

Connect an MCP client to https://api.gosummer.ai/mcp (Streamable HTTP). The client discovers Summer's authorization server and asks you to approve the connection in your browser. Tools follow the permissions you grant.

An MCP server cannot read files or environment variables on your computer. Steps that would move a secret, such as saving a credential value or creating a Messenger installation, return the exact summer CLI command to run locally instead of asking for the value.

Cases and approvals#

With cases.read, summer cases list, summer cases get ID and summer cases attachment CASE FILE read your company's own records. Text search over cases is not available through the API yet. An attachment is only returned for the case that owns it. summer investigations request CASE asks Summer to investigate; a finished investigation is not approval. summer actions prepare CASE --plan-request ID prepares a saved plan's exact work and returns awaiting_human_approval. A person approves it in Summer, and Summer's backend executes it. A lost response is never retried as a second execution.

To take over a website conversation, summer messenger pause CONVERSATION stops automatic assistant replies at once so a person can answer in Summer; summer messenger resume CONVERSATION hands it back. summer team lists members and pending invitations; invitations and role changes stay in Summer.

Automation#

A service account lets a recurring job read events without a person's browser session:

summer service-accounts save NEW_UUID --name "Event sync" --scopes events.read --environments staging \
  --expected-version 0 --write-secret-to .env.local:SUMMER_SERVICE_ACCOUNT_SECRET -c COMPANY_ID

Exchange its ID (sa_<id>) and secret for a token with the client_credentials grant, then read /v1/companies/{company}/environments/{environment}/events?after=CURSOR and resume from next_cursor.

Signed webhooks send the same events to an https endpoint. Verify each delivery before trusting it, and deduplicate by Summer-Event-Id:

import { createHmac, timingSafeEqual } from "node:crypto";
const [t, v1] = request.headers["summer-signature"].split(",").map(part => part.split("=")[1]);
const expected = createHmac("sha256", process.env.SUMMER_WEBHOOK_SECRET).update(`${t}.${rawBody}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
const valid = fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

If your receiver missed events, summer webhooks replay ID --after CURSOR queues everything after that cursor again. Disabling a service account or webhook takes effect immediately. Events carry identifiers and action names, never secret values or message text.