---
title: "Protocol and integration"
description: "Bucky's MCP transport, discovery documents, calling the server with curl, and how to read result statuses."
last_updated: "2026-10-05"
---

This page is for developers building or testing an MCP client against Bucky. To connect
an existing assistant, see [Connect](/docs/mcp/connect).

## Transport

- **Endpoint:** `POST https://buckybuild.com/api/mcp`
- **Transport:** Streamable HTTP. `GET` and `DELETE` return `405`. Don't wrap the
  endpoint in a stdio or SSE bridge.
- **Protocol versions:** MCP `2026-07-28`, plus a compatibility path for 2025-era
  clients that use `initialize`.
- **State:** stateless. The server may send an `Mcp-Session-Id` header, but no request
  depends on it.
- **Capabilities:** tools, prompts, resources, completions, and the MCP Apps extension
  for [interactive views](/docs/mcp/views-and-prompts).
- **Request size:** up to 64 KiB.

## Discovery

Clients and agents can find the server before connecting:

- `https://buckybuild.com/.well-known/mcp/server-card.json` — name, version, protocol,
  and endpoint.
- `https://buckybuild.com/.well-known/mcp/manifest.json`
- OAuth metadata — see [Sign-in, permissions, and limits](/docs/mcp/auth-and-limits).

The server card marks tools as dynamic. `tools/list` is the authority, and it returns
the same catalog whether or not you are signed in.

## Try it with curl

Every request needs `Content-Type: application/json` and an `Accept` header that
includes both `application/json` and `text/event-stream`. Leaving either out returns
`406`.

**Discover the server (MCP 2026-07-28).** This version needs no initialization
handshake:

```bash
curl --fail --silent https://buckybuild.com/api/mcp \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'Mcp-Method: server/discover' \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"}}}}'
```

**Initialize (2025-era clients):**

```bash
curl --fail --silent https://buckybuild.com/api/mcp \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'
```

The answer may arrive as an SSE `data:` frame, which is valid Streamable HTTP.

**List tools:**

```bash
curl --fail --silent https://buckybuild.com/api/mcp \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

**Call a tool that needs no sign-in:**

```bash
curl --fail --silent https://buckybuild.com/api/mcp \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"explainFeasibilityStatus","arguments":{"status":"not_extracted"}}}'
```

**Call a signed-in tool.** Get the access token through OAuth (authorization code with
PKCE, with `resource=https://buckybuild.com/api/mcp`). An agent can use the
[`/auth.md`](https://buckybuild.com/auth.md) flow with the same `resource` instead. The
token starts with `bmcp_at_` and works only at `/api/mcp`. Don't paste a Bucky user
access token; that path is deprecated (see
[Bearer tokens](/docs/mcp/auth-and-limits#bearer-tokens)). Read the token without
echoing it:

```bash
read -r -s 'BUCKY_MCP_TOKEN?Bucky MCP access token (bmcp_at_…): '
export BUCKY_MCP_TOKEN

curl --fail --silent https://buckybuild.com/api/mcp \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header "Authorization: Bearer ${BUCKY_MCP_TOKEN}" \
  --data '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"getFeasibilitySnapshot","arguments":{"address":"4170 Sophia St, Vancouver BC"}}}'

unset BUCKY_MCP_TOKEN
```

Without a valid token, signed-in tools return `401` with `WWW-Authenticate`, which is how
OAuth clients know to start sign-in.

## Result statuses

Every fact in a feasibility result carries a `status`. **A `null` value means nothing
without its status.** `no_limit_in_bylaw` and `not_extracted` both have `value: null`
and mean opposite things.

**Coverage** — can Bucky answer for this address?

| Status                      | Meaning                                                                   |
| --------------------------- | ------------------------------------------------------------------------- |
| `live`                      | Bucky found a usable parcel in a covered place.                           |
| `live_unavailable`          | The place is covered, but this address didn't resolve to a usable parcel. |
| `planned_not_live`          | Bucky plans to cover this place; it isn't live yet.                       |
| `geo_division_uncatalogued` | Bucky recognized the place but hasn't catalogued it.                      |
| `unseeded_place`            | The address is in a place Bucky has no record of.                         |
| `geocode_failed`            | Bucky couldn't place the address.                                         |

When an address is out of coverage, the call still succeeds with `answered: false` and a
`coverage` block that says why. `coverage.eligibilityKnown: false` means Bucky couldn't
tell either way, which is different from knowing the place isn't covered.

**Facts** — where a value came from:

| Status                   | Meaning                                                                                 | How to report it                                 |
| ------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `cited`                  | Read from the bylaw, with a citation.                                                   | Report it with the citation.                     |
| `cited_conditional`      | A conditional rule applies, and Bucky worked out which tier fits this site.             | Report it with the condition.                    |
| `conditional_unresolved` | Conditional tiers exist; Bucky couldn't tell which applies.                             | Unknown. Don't pick or average a tier.           |
| `no_limit_in_bylaw`      | The bylaw sets no zone-level limit.                                                     | A real answer: no zone-level limit, not zero.    |
| `not_extracted`          | Bucky hasn't extracted this value.                                                      | Unknown. Never "no limit" and never zero.        |
| `site_specific_schedule` | The zone has its own site-specific bylaw (for example CD-1 or PD).                      | Unknown. Read the site-specific bylaw.           |
| `unverified_default`     | A stored value with no citation behind it.                                              | A lead, not a verified rule.                     |
| `derived_from_cited`     | Calculated by applying a cited rule to this site, for example a setback from lot depth. | Report it with the rule, not as a quoted figure. |
| `defaulted`              | A fallback value with no citation.                                                      | Indicative only.                                 |
| `missing`                | Nothing is recorded for this constraint.                                                | Unknown.                                         |

`explainFeasibilityStatus` and the `bucky://status/{status}` resource return the same
explanations, with a next step for each. See also [Citations](/docs/resources/citations).


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
