MCP for AI agents

Connect an OAuth-capable AI agent to Acked.

Connect from Codex

Acked provides a remote Streamable HTTP MCP server at https://api.acked.dev/mcp.

codex mcp add acked --url https://api.acked.dev/mcp
codex mcp login acked

Complete Acked sign-in and consent in the browser. Confirm the connection with codex mcp list or /mcp in the Codex terminal UI.

Another client can connect when it supports OAuth protected-resource discovery, dynamic client registration, PKCE, and a browser redirect.

Understand authorization

The browser flow requests this scope set:

openid,offline_access,acked:read,acked:write

Scope	Purpose
`openid`	Identify the signed-in Acked account.
`offline_access`	Refresh the client grant.
`acked:read`	Read organizations and product configuration.
`acked:write`	Create and change product configuration.

Acked checks current organization membership and role for every operation. A role or membership change takes effect without waiting for token expiry.

MCP uses interactive OAuth. Acked API keys do not authenticate the MCP endpoint.

Choose the narrowest credential

Credential	Authority	Alert payload
Service-scoped `ingest_url`	Raise alerts for one integration's service.	No authorization header and no `service_id`.
Alert ingest API key	Raise alerts across its organization through `/v1/alerts`.	Bearer header and `service_id`.
Full product API key	Manage customer `/api/*` routes and send direct alerts.	Bearer header, plus `X-Acked-Org` for organization-scoped management.
MCP OAuth grant	Act as the signed-in person through MCP.	Keep it in the MCP client. Never hand it to an emitter.

Prefer one service-scoped URL for one emitter. The URL selects the service, so the sender cannot target another service and does not carry Acked ids in its payload.

Set up a project

Start with a specific request:

Set up this project's services and alerts in Acked.
Reuse existing configuration and ask before sending a real test alert.

The agent can list organizations, inspect configuration, create services and sources, configure destinations, and send an approved test alert. A new service includes a service-scoped ingest URL for its default integration.

Use list_organizations when the agent must choose an organization.

A native JSON emitter needs only the URL and its alert fields:

curl -X POST "$ACKED_INGEST_URL" \
  -H 'content-type: application/json' \
  -d '{"event_key":"checkout-5xx","title":"Checkout errors","priority":"high"}'

reveal_integration_url retrieves an existing URL without changing it and records the reveal in Acked's ledger. rotate_integration_url immediately invalidates the old URL and returns a replacement. Reveal when a destination must be reconfigured. Rotate only when the credential is lost or exposed.

Choose MCP or direct API access

Use MCP for interactive agent work tied to a person’s membership and role. Use an API key for unattended organization-wide HTTP automation. Use a service-scoped integration URL when one caller only emits alerts for one service.

See HTTP API for the OpenAPI contract, credential authority, receipts, webhook templates, and TypeScript examples. See API keys for credential handling and the Alert API for deduplication and recovery behavior.

Troubleshoot OAuth

`oauth_required` or HTTP 401

Run codex mcp login acked and complete the browser flow.

`requested resource invalid`

Remove stale configuration and add the production resource again.

codex mcp logout acked
codex mcp remove acked
codex mcp add acked --url https://api.acked.dev/mcp
codex mcp login acked

`insufficient_scope`

Request the complete supported scope set in a new grant.

codex mcp logout acked
codex mcp login acked --scopes openid,offline_access,acked:read,acked:write

An organization is missing

Ask the client to run list_organizations. The signed-in account must have an active membership and sufficient role.

Protect returned credentials

Service ingest URLs, API keys, webhook signing secrets, and protected headers are credentials. Store them in the destination system or a secret manager. Rotate any credential exposed in chat or logs.