# Kismet Developer MCP

> Build with your coding agent using Kismet recipes, API references, Fixture setup, developer access management, and telemetry verification.


Build Kismet-powered experiences with your coding agent. Connect the Developer MCP in Claude, Claude Code, Codex, Lovable, or another MCP client to find integration recipes, configure Fixtures, manage developer access, and verify telemetry using Kismet's supported contracts.

Start without signing in to explore the API, choose a recipe, and validate your integration. When you are ready to configure a collection, [choose the authentication method](#authentication-and-access) for that task.

> **For builders, not guest sessions**
>
> The Developer MCP supports development, setup, and aggregate telemetry verification. Your deployed site's guest-account and booking flows use the SDK or REST API, not the MCP. Never send a guest session token to this endpoint.

## Connect

Endpoint: `https://mcp.kismet.travel/developer-mcp`

Transport is Streamable HTTP over POST. Recipes and documentation need no credential. Connect first, then use your client's Kismet sign-in flow for collection management or its secure credential configuration for API-key access. These are separate authentication modes; see [Authentication and access](#authentication-and-access).

### Claude and Claude Code

For the complete Claude experience, install the plugin. In Claude, open
**Customize → Plugins → Personal plugins → + → Add marketplace**, add
`https://github.com/kismet-tech/kismet-platform-plugin`, then install
**Kismet Developer**.

In Claude Code, run:

```text
/plugin marketplace add kismet-tech/kismet-platform-plugin
/plugin install kismet-developer@kismet-platform
```

If you only want the remote MCP without the bundled skills, run:

```bash
claude mcp add --transport http kismet-developer https://mcp.kismet.travel/developer-mcp
```

For collection setup, use the client's authentication action to sign in with Kismet. For installation capability inspection or telemetry, configure a Developer API key through the client's secure credential storage. Do not paste a server key into a prompt, command history, or checked-in configuration.

### Codex

Install the full plugin:

```sh
codex plugin marketplace add kismet-tech/kismet-platform-plugin
codex plugin add kismet-developer@kismet-platform
```

Open a new task after installation so Codex loads the skills and MCP server.

### Lovable

Open **Connectors → + → MCP server**, name the server `Kismet Developer`,
and enter the endpoint above. Keep **OAuth** selected, then choose
**Add & authorize**. See [Lovable's custom MCP setup](https://docs.lovable.dev/integrations/custom-mcp).
The connection is available
to Lovable while it builds your application; it does not add Kismet runtime
behavior to the deployed application.

Lovable receives the canonical tools, resources, prompts, and recipes through
the MCP. It does not install the six local workflow skills bundled with the
Claude and Codex plugin, so begin with: “Call `list_recipes`, choose the
smallest available recipe for this task, then call `plan_integration` before
editing the application.”

For API access setup, choose **OAuth** and complete **Sign in with Kismet** on the connector. Refresh the tools after sign-in, then ask the agent to [create scoped access](https://developers.kismet.travel/guides/developer-access.md#set-up-through-your-coding-agent). You do not need to obtain a key from the Kismet dashboard first. Before requesting a server key, establish how the client will save the once-only result to your server's secret store; the MCP does not automatically populate Lovable secrets.

**Any client, by hand**

```bash
curl -s -X POST https://mcp.kismet.travel/developer-mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Skills and plugins

You can use the MCP without a plugin. Its tools, recipe and documentation
resources, and `build:<id>` prompts are all available through the protocol.

A plugin adds one thing on top: **skills**, files your agent loads at the start of a session rather than fetching mid-task, so it already knows the conventions before you ask it anything. Kismet publishes plugins through a public marketplace repository, [kismet-tech/kismet-platform-plugin](https://github.com/kismet-tech/kismet-platform-plugin).

| Plugin | Who it is for | Status |
| --- | --- | --- |
| `kismet-operators` | Property managers running a Kismet business from an AI client: catalogs, guest journeys, demand, Insiders email, ads and audiences | available |
| `kismet-developer` | Builders integrating the Developer API, SDK, and Fixtures | [available](https://github.com/kismet-tech/kismet-platform-plugin/releases/tag/kismet-developer-v0.1.0) |

The developer plugin contains six workflow skills for SDK sites, semantic search, branded guest accounts, TEST booking, fixture-backed builds, and pre-deployment validation. The MCP recipe and operation registry remains canonical, so the skills fetch current contract details instead of carrying a second API description.

Note that `kismet-operators` is a different audience, not an earlier version of the same thing. It operates a Kismet account; it does not help you build against the Developer API.

## Authentication and access

Your authentication method determines which tools you can use. A tool appearing in `tools/list` does not by itself grant permission to call it.

| Access method | What it enables | What you need |
| --- | --- | --- |
| No sign-in | Documentation, recipes, operation discovery, integration planning and validation | The public endpoint |
| Sign in with Kismet (OAuth) | Developer application, installation, and credential management; collection Fixture setup | A Kismet account with the required role on the target collection |
| Developer API key | Installation capability inspection; authorized server keys also enable telemetry operations | An active TEST or LIVE credential with the required grants |
| Guest sign-in | Your site's visitor account, saves, and guest flows—not access to the Developer MCP | A separate [guest-account integration](https://developers.kismet.travel/sdk.md) using same-origin BFF routes |

### Sign in to manage a collection

Use **Sign in** or **Authenticate** on the Developer MCP connection in your client, then complete the Kismet OAuth flow. The connection uses the `developer:mcp` scope for this endpoint. Your existing collection roles still apply; signing in does not grant new roles.

- Developer credentials: collection `ADMIN` or `DEVELOPER`, or `GLOBAL_OWNER` authority. The target collection is checked on every action.
- Fixture status: collection access. Fixture configuration and publishing: `ADMIN` or `MEMBER` on the target collection.
- Domain registration and managed guest-account availability: `ADMIN`. These actions have additional checks even when other Fixture tools are visible.

A `DEVELOPER` role alone does not authorize Fixture writes. If your client cannot complete OAuth, use [Kismet's Developer API settings](https://developers.kismet.travel/guides/developer-access.md) for credential management and the collection dashboard for Fixture setup.

### Connect an installation with an API key

Create a credential using the [access guide](https://developers.kismet.travel/guides/developer-access.md), then configure `Authorization: Bearer …` in your MCP client's secure connection settings. A publishable or server key can inspect its own installation using `describe_capabilities`; publishable keys also require their authorized origin. Telemetry tools require a **server key** with `telemetry.read` or `telemetry.configure`; publishing a mapping requires `telemetry.configure`.

An API key cannot create other keys or act as a signed-in collection administrator. Conversely, signing in with OAuth does not supply a server key to telemetry tools. If you need both workflows, configure separate connections for OAuth and API-key access.

Missing credentials permit public discovery only. Invalid, expired, or revoked credentials receive `401`; they are not silently treated as anonymous. A valid identity without the required authority is refused. Resolve the credential or role problem instead of retrying with broader access.

## Tools by task

Use the current `tools/list` response to discover the tools available to your connection. The groups below explain what to use and when authentication is required.

### Find, plan, and validate an integration

These tools work without sign-in. `describe_capabilities` also accepts an API key for installation-specific results.

| Tool | What it does |
| --- | --- |
| `list_recipes` | Lists integration recipes with id, domain, status, summary, and the operations each uses. Filter by `domain` or `status`. |
| `get_recipe` | One recipe in full as Markdown: goal, what to use, operations, capabilities, environments, acceptance, and prohibitions. Same text as the `kismet://recipes/<id>` resource. |
| `search_docs` | Token search over the shipped API reference, quickstart, `llms.txt`, and the recipes. Returns resource URIs your client can read in full. |
| `describe_capabilities` | Anonymous: the shipped operations and the capability each needs. With a credential: environment, granted capabilities, unlocked and not-granted operations, allowed origins, and whether writes are sandbox on this installation. |
| `get_operation` | Returns the canonical generated reference for one shipped operation, including capability, request, response, errors, and examples. |
| `plan_integration` | Builds a bounded plan for one available recipe, framework, and explicit `fixtures` or `live` data mode. |
| `get_fixture_plan` | Returns one Fixture's registry status, dependencies, install methods, data coverage, settings, and missing commerce actions. |
| `validate_integration` | Checks supplied source and configuration text for deterministic contract violations. It accepts content, never a filesystem path. |
| `explain_problem` | Explains a stable Kismet problem code and the safe response. |

### Manage developer access

Sign in with Kismet and use an authorized `ADMIN` or `DEVELOPER` collection role (or `GLOBAL_OWNER`). Review the collection, environment, grants, and origins before confirming a change.

| Tool | What it does |
| --- | --- |
| `list_developer_applications` | Find applications for the collection. |
| `create_developer_application` | Create the integration's application record. |
| `activate_developer_application` | Activate an application before installing it. |
| `create_developer_installation` | Create a TEST or LIVE installation with explicit grants and origins. |
| `get_developer_installation` | Inspect an installation's configuration. |
| `list_developer_credentials` | Inspect credential inventory and lifecycle metadata. |
| `issue_developer_credential` | Issue a credential for an installation. Server secrets are returned once. |
| `revoke_developer_credential` | Revoke a credential after confirming which integration uses it. |
| `replace_developer_test_guest_identities` | Replace the TEST guest identity list for deterministic sandbox authentication. |
| `register_software_app` | Preview and register a disabled app with its hosted manager panel, description, builder, and integration branding. Requires an existing authorized installation. |
| `update_software_presentation` | Preview and replace an app's branding without changing its settings or experiment revision. |

Have the agent deliver a newly issued server secret directly to your authorized server secret store, not to chat or source code. See [Inspect, rotate, and revoke credentials](https://developers.kismet.travel/guides/developer-access.md#inspect-rotate-and-revoke-credentials).

#### Set up event and webhook access

For a custom integration that appears in **Apps**, follow [Build an app for Kismet](https://developers.kismet.travel/guides/software-modules.md).
App registration uses OAuth and does not require a key in chat. Your hosted runtime
still uses its own restricted server credential; integration logos do not configure vendor access.

The same OAuth tools configure `events.read`, `webhooks.read`, `webhooks.write`, and explicit event-family grants (`payment_methods.events.read` and/or `guest_wallet_requests.events.read`). Start with a separate TEST installation and no browser origins for a server-only integration. Preview the exact grants before confirmation; they do not authorize guest sign-in, card capture, bookings, or charges.

Follow [Developer events and signed webhooks](https://developers.kismet.travel/guides/developer-events.md#set-up-access-with-oauth) for a ready-to-use setup prompt and receiver implementation. MCP handles the application, installation and credential lifecycle; destination creation and event delivery/replay use the installation credential through SDK/REST. They are not additional OAuth management tools, and the collection-manager webhook service is separate.

### Configure and verify Fixtures

Sign in with Kismet. Status requires collection access; writes require `ADMIN` or `MEMBER`, except the two ADMIN-only setup tools noted below.

| Tool | What it does |
| --- | --- |
| `get_fixture_status` | Inspect the collection's Fixture configuration and staging status. |
| `provision_staging_proxy` | Prepare a staging proxy when one is missing. |
| `set_fixture_rules` | Preview and apply a draft rule set. Preserve unrelated rules: the set is replaced, not appended. |
| `set_fixture_css` | Update the shared collection stylesheet. This can affect production immediately; it is not staging-only. |
| `publish_fixtures` | Explicitly promote the reviewed Fixture configuration to production. |
| `register_collection_domain` | Register a STAGING, PREVIEW, or DEVELOPMENT host. ADMIN only; production domains are registered in the dashboard. |
| `prepare_collection_domain` | Issue a 30-minute HTTPS ownership challenge for a registered non-production host. ADMIN only; preview before confirming. |
| `verify_collection_domain` | Check the exact public proof and mark that domain verified. ADMIN only; preview before confirming. |
| `set_managed_guest_availability` | Configure managed guest-account availability for staging or production. ADMIN only; preview before confirming. |

Start with `get_fixture_plan` to check supported installation targets and data coverage, then `get_fixture_status`. Preview configuration changes, verify the rendered staging page in a browser, and request approval before `publish_fixtures`. Saved configuration is not proof that the fixture renders correctly.

### Verify a staging domain

Registering a hostname does not prove that you control it. Sign in with a Kismet
account that has **ADMIN** access to the collection, then ask your coding agent to:

1. Preview `prepare_collection_domain` with `collection_slug` and the bare
   `hostname`, such as `staging.your-site.com`. Repeat with `confirm: true` to
   receive `proof`, `verification_url`, `content_type`, and `expires_at`.
2. Serve the exact `proof` body at the returned HTTPS URL:
   `https://staging.your-site.com/.well-known/kismet-domain-verification`.
   Return **200** and `Content-Type: text/plain`. No trailing newline, HTML,
   sign-in requirement, or redirects.
3. Preview `verify_collection_domain` with the same collection and hostname,
   then repeat with `confirm: true`. Success returns `status: VERIFIED`.

The proof is public, not an API key. It expires after **30 minutes**; preparing
another challenge replaces the previous one. You may remove the proof route
after successful verification. Existing verified domains are left unchanged.

If verification fails, check the exact hostname, body, content type, and status.
Cached older proofs and trailing newlines do not match. Private-network hosts
and redirects are rejected. Prepare a fresh challenge if the previous one expired.

These tools support **STAGING**, **PREVIEW**, and **DEVELOPMENT**, not production
domains. They use manager OAuth, not guest sign-in or a Developer API key; there
is no server-key SDK operation that grants domain ownership. Check your connected
MCP's tool list before starting.

Verification does not change installation origins, API grants, or email permissions.
For real staging participation, separately review the exact allowed origin and
participation settings after verification.

### Verify and configure telemetry

Use a server API key. Reads and previews require `telemetry.read` or `telemetry.configure`; publishing requires `telemetry.configure`. The tool's `environment` is the site environment: `production` requires a LIVE installation; `staging`, `preview`, `development`, and `local` require TEST. Do not send `TEST` or `LIVE` as the tool's environment value.

| Tool | What it does |
| --- | --- |
| `get_telemetry_mapping` | Read the mapping, revision, and rollback history. |
| `preview_telemetry_mapping` | Dry-run a profile against up to 200 recent received events, without writes or replay. Returns evidence and a digest for the reviewed profile. |
| `publish_telemetry_mapping` | Publish the exact previewed profile using its digest and expected revision. Affects future ingestion; a previous profile can be used for rollback. |
| `inspect_telemetry` | Inspect aggregate stored-event evidence, including mapped fields and events received since publication. No guest records, visitor IDs, or IP addresses are returned. |

Event receipt alone does not prove consent enforcement, returning-visitor recovery, or booking attribution. Mapping tools do not configure site consent or deploy tracking JavaScript. Follow the [telemetry integration guide](https://developers.kismet.travel/telemetry.md) for those parts.

## Recipes

A recipe is a versioned, repository-owned artifact: what to build, which Developer API operations it uses, what must be true when it is done, and what it must never do. Your agent should start with `list_recipes`, then `get_recipe` for the one that matches the job.

Every recipe carries a **status**, and the status is part of the contract:

- **available**: every operation the recipe needs is shipped and documented. Build against it.
- **preview**: at least one operation it needs is on a review branch and not deployed. The recipe says so in its own text. Use it to shape architecture; do not generate code that assumes it is live.
- **planned**: at least one operation it needs is designed and not built. Architecture only.

Prompts (`build:<recipe-id>`) exist only for available recipes. A prompt is an invitation to build, and the server does not invite building against unshipped contracts.

Available recipes cover rental list/detail, synchronized availability, natural-language BookableProduct search, TEST booking requests, branded guest authentication, guest self, memberships, email state, saved-payment readiness, saves, signed-in TEST booking, and session recovery. Benefit projections remain planned and are labeled as such.

The semantic-search recipe uses `searchBookableProducts` for LIVE and TEST API data. For a Fixture-based implementation, use `get_fixture_plan` to verify the semantic-search component's supported installation target and data coverage. Explicit local fixture data is suitable for UI development, but is not evidence of live semantic ranking.

## Resources

- `kismet://recipes/<id>`: one recipe, Markdown
- `kismet://docs/reference/<operationId>`: one operation reference page, the same Markdown twin linked from each page in this site
- `kismet://docs/quickstart`: the quickstart
- `kismet://docs/llms.txt`: the machine-readable index of everything shipped

Operation references are generated from the reviewed Developer API contract. Use `get_operation` for the server's current reference and this site's [OpenAPI artifact](/openapi.json) when checking compatibility with your installed SDK.

## Boundaries

- Guest tokens are not accepted. Guest, booking, and saves reads belong in the SDK or REST API behind the browser/BFF boundary. Aggregate telemetry inspection is a separate builder operation.
- TEST and LIVE are separate installations with separate credentials, and crossing them is refused. `describe_capabilities` on a TEST key tells you writes create sandbox rows; on a LIVE key it tells you sandbox-only operations are refused.
- Server keys (`kismet_sk_…`) never belong in a browser, a repository, a build artifact, or a shared MCP config. Publishable keys (`kismet_pk_…`) are origin-bound and browser-safe.
- Use only operations and Fixture installation targets returned by the current contract. A proposed recipe or visual component does not establish a shipped API or payment action.

## Discovery documents

- [OAuth protected-resource metadata](https://mcp.kismet.travel/.well-known/oauth-protected-resource/developer-mcp) identifies this endpoint and `https://kismet.travel` as its authorization server. It advertises the `mcp:tools` and `developer:mcp` scopes for client discovery.
- `https://kismet.travel/.well-known/mcp.json` lists every Kismet MCP server, including this one, under `servers.developer`.