# MCP transport and authentication

Source: https://neondeerdata.com/docs/api/mcp/protocol/

Connect an MCP client and discover the tools its authorization permits.

## Server address

Send MCP JSON-RPC messages to `POST https://api.neondeerdata.com/mcp` over HTTPS. The server uses the HTTP transport and returns JSON responses. Authenticate using an approved sign-in connection or an MCP-purpose API key in `Authorization: Bearer <credential>`. Cookies do not authenticate MCP calls.

## Initialization and tools

The server supports the `2026-07-28` profile and the legacy `2025-11-25` initialization flow. Let your MCP client negotiate its supported version. Clients using the legacy flow start with `initialize` and send the initialized notification. Use `tools/list` to discover the tool names, descriptions, input schemas, output schemas, and annotations offered to the connection. Resource access is checked when a tool runs; seeing a tool in the list does not grant access to every table, object, or workflow it can name.

Call `tools/call` with `name` and an `arguments` object. Native argument names match the [action reference](https://neondeerdata.com/docs/api/mcp/actions/). For a keyed write, `request_key` is required; it corresponds to REST's `Idempotency-Key` header. Keep it when retrying the same intended action.

The newer profile supports `server/discover`; the legacy profile also supports `ping` and the initialized notification. It exposes tools, without an MCP resource or prompt catalog. JSON-RPC batches and a GET event stream are not supported. An unsupported method is refused.

## Authentication discovery

An unauthenticated request receives a Bearer challenge with protected-resource metadata. Clients should follow discovery rather than invent token endpoints. These routes belong to the API host:

| Method | Path                                                | Purpose                                                    |
| ------ | --------------------------------------------------- | ---------------------------------------------------------- |
| GET    | `/.well-known/oauth-protected-resource`             | Protected-resource discovery.                              |
| GET    | `/.well-known/oauth-protected-resource/mcp`         | MCP-specific protected-resource discovery.                 |
| GET    | `/.well-known/oauth-authorization-server/mcp-oauth` | Authorization, token, revocation, and capability metadata. |
| GET    | `/mcp-oauth/authorize`                              | Begin a sign-in authorization request.                     |
| POST   | `/mcp-oauth/register`                               | Register a client with supported callback URLs.            |
| POST   | `/mcp-oauth/token`                                  | Exchange an authorization code or refresh token.           |
| POST   | `/mcp-oauth/revoke`                                 | Revoke a token.                                            |

The sign-in flow uses authorization code with PKCE and supports refresh tokens. Supported clients can use client metadata discovery or dynamic client registration. Registration accepts supported callback URLs; it does not grant access to an organization. Organization invitation, sign-in, and connection permissions still apply.

The consent page's context and decision calls are handled by Neon Deer's signed-in interface. An integration should use the authorization flow rather than call those internal session routes.

## Results and failures

Read the tool's structured result and any operation status it returns. A tool result can report a business failure even when the HTTP transport succeeded. A successful operation can also contain unsuccessful items. See [operations](https://neondeerdata.com/docs/api/operations/) and [requests and retries](https://neondeerdata.com/docs/api/requests/).

Malformed JSON, invalid messages, unsupported methods, and unknown tools produce protocol errors. Authentication, permission, availability, and temporary failures can be refused before the tool runs. Inspect the returned error and request ID; never include a credential when asking for support.

Tool annotations describe the action's effects. They do not grant permission or guarantee that an AI client will request confirmation. Review [permissions](https://neondeerdata.com/docs/api/permissions/) before allowing writes.