# Connect your agent to Concya

Concya is the operating layer for restaurants, hotels, and property portfolios. An agent that speaks MCP can connect to the house, search venues, ask questions, and request bookings.

## Endpoint

- **Name:** concya
- **Transport:** Streamable HTTP (MCP)
- **URL:** `https://www.concya.com/api/protocol/mcp`

`venue_search`, `venue_profile`, and `availability_check` work without a key. `venue_ask`, `booking_hold`, `booking_status`, and `booking_cancel` need a Concya partner key:

```
Authorization: Bearer <your Concya key>
```

If you already know the venue handle, the per-venue endpoint is `https://www.concya.com/api/protocol/v/<handle>/mcp`.

## Add the server

In your agent's MCP settings, add a remote server named `concya` with the URL above. There is no OAuth flow yet: public reads need no credential, and keyed tools take a partner key.

For a local test, run the MCP Inspector and enter the URL above:

```bash
npx @modelcontextprotocol/inspector
```

## Tools

| Tool | What it does | Key |
|------|--------------|-----|
| `venue_search` | Search the live venue directory by name, city, or cuisine. Returns handles. | No |
| `venue_profile` | Hours, menu highlights, policies, and whether reservations are open. | No |
| `availability_check` | Whether the venue takes requests, its party-size cap, and whether a date/party is requestable. Not live slot inventory. | No |
| `venue_ask` | Ask a natural-language question about the venue. | Yes |
| `booking_hold` | Stage a pending reservation request. | Yes |
| `booking_status` | Poll a booking created with your key. | Yes |
| `booking_cancel` | Cancel a pending request made with your key. | Yes |

## Booking rules

- `booking_hold` creates a **request**, not a confirmed table. The venue confirms in its approval book. Never tell a guest a pending hold is confirmed.
- Pass `id` as your idempotency key. Retrying with the same `id` returns the original request instead of creating a second one.
- `availability_check` answers requestability. It does not list open slots.
- `booking_status` only returns bookings made with the same key.
- If a booking also lives in Resy or OpenTable, cancelling through Concya carries a warning: the external booking still needs the house to cancel it there.

## Check it works

1. Call `venue_search` with a query such as `"Philadelphia"`.
2. Call `venue_profile` with a returned handle.
3. Call `availability_check` for that handle.
4. With a partner key, call `venue_ask` with a short question.

Protocol: `concya/0.1`. Full envelope and method definitions are served at `https://www.concya.com/api/protocol/openapi.json`.
