Perse Connectors

API & MCP reference

This page is temporarily unavailable — retrying…

Get started

Use the client ID and secret you signed in with. They are never shown on this page — replace the <CLIENT_ID> and <CLIENT_SECRET> placeholders with your own.

Connect Optimise to Claude (claude.ai or Claude Desktop)

Open Settings → Connectors and choose Add custom connector.
Name it Perse Optimise and paste this as the server URL:
```
https://optimise-mcp.perse.io/alpha/mcp
```
Open Advanced settings. Enter your Client ID as the OAuth Client ID and your Client secret as the OAuth Client Secret.
Choose Add, then Connect. If an authorisation window opens, let it finish; it closes by itself.
In a new chat, switch the Perse Optimise connector on from the tools menu and ask for something.

Your client secret is a password for your organisation. Enter it only in Claude's connector form, never in a chat message.

Connect NCC to Claude (claude.ai or Claude Desktop)

Open Settings → Connectors and choose Add custom connector.
Name it Perse NCC and paste this as the server URL:
```
https://ncc-mcp.perse.io/alpha/mcp
```
Open Advanced settings. Enter your Client ID as the OAuth Client ID and your Client secret as the OAuth Client Secret.
Choose Add, then Connect. If an authorisation window opens, let it finish; it closes by itself.
In a new chat, switch the Perse NCC connector on from the tools menu and ask for something.

Your client secret is a password for your organisation. Enter it only in Claude's connector form, never in a chat message.

Connect Switch to Claude (claude.ai or Claude Desktop)

Open Settings → Connectors and choose Add custom connector.
Name it Perse Switch and paste this as the server URL:
```
https://switching-mcp.perse.io/alpha/mcp
```
Open Advanced settings. Enter your Client ID as the OAuth Client ID and your Client secret as the OAuth Client Secret.
Choose Add, then Connect. If an authorisation window opens, let it finish; it closes by itself.
In a new chat, switch the Perse Switch connector on from the tools menu and ask for something.

Your client secret is a password for your organisation. Enter it only in Claude's connector form, never in a chat message.

Start building against the Optimise MCP server with a prompt. Give it to Claude Code (or your AI coding assistant) and it builds a working app that calls the live server — there is no separate REST integration to write.

Start the development

Copy the prompt below.
Replace the part in <angle brackets> with what you want to build, and change the example workflow to your own steps.
Open Claude Code (or another AI coding assistant) in an empty project folder and paste it.
When it asks for credentials, put your client ID and secret in the project's .env file yourself — never in the chat.
Run the app. The assistant checks its work by using it in the browser, against the live server.

prompt — copy into your assistant

# Prompt: Building a live Perse Optimise MCP connector demo

Build a <sample UI app / demo: describe what you want, for example "a small web app"> for the Perse Optimise MCP connector.

Workflow (an example: replace it with your own steps):

1. Search for a UK business address by postcode (optimise_address_search) and let the user pick one.
2. Create a portfolio (lcr_portfolio_create) and add the chosen site to it with its meter (lcr_site_add).
3. Show the site's building details (lcr_site_details).
4. Show the recommended low-carbon measures with cost, yearly saving and payback (lcr_site_recommendations).
5. Let the user add a measure to the plan (lcr_interest_create) and show the plan (lcr_site_plan_measure).

## MCP Server Verification

Before writing any mock/backend code, check whether the Optimise connector is a real, publicly reachable MCP server using Streamable HTTP (plain JSON-RPC over POST), rather than assuming it only works inside this chat session.

Its endpoint is:

`https://optimise-mcp.perse.io/alpha/mcp`

Use exactly this URL: the bare `/mcp` path is retired and answers 410. Confirm the server is reachable with a plain `initialize` POST. Without credentials it answers 401 ("needs your organisation's client credentials"). That confirms the server is live and speaking MCP, so treat it as success for this check, not as a failure.

If the server responds:

- Wire the app to call the MCP server live, directly.
- Use a thin browser-side JSON-RPC client.
- Track the `mcp-session-id` response header.
- Route MCP requests through a same-origin dev-server proxy (for example Vite's `server.proxy`) to avoid CORS.
- Do **not** build an Express/mock backend for this.

## How the protocol works

- A session is: `initialize`, then `notifications/initialized`, then any number of `tools/list` and `tools/call`, each carrying the `mcp-session-id` header that `initialize` returned.
- Send `content-type: application/json` and `accept: application/json, text/event-stream`.
- Replies arrive as Server-Sent Events: read the `data:` line of each.
- A successful tool call returns its data in `result.structuredContent`. A failure has `result.isError: true` and a plain-language message in `result.content`.
- Discover the tools and their input schemas with `tools/list`. Do not guess tool names or arguments.

## Authentication

Credentials go on every request as these headers:

    x-optimise-client-id: <CLIENT_ID>
    x-optimise-client-secret: <CLIENT_SECRET>

Read the values from environment variables (PERSE_CLIENT_ID and PERSE_CLIENT_SECRET) in the dev server, and have the same-origin proxy add the headers, so the secret never reaches browser code, is never committed, and is never pasted into this chat. Create a `.env.example` with the variable names only.

Do not test authenticated tool calls with raw `curl`, as that gets blocked as bypassing the sanctioned tool interface.

Verify authenticated flows only by:

- actually using the running app in the browser, or
- using your own MCP tool calls.

## Existing Implementations

Before building from scratch, check for an existing reference implementation, such as other demo folders on disk.

Only fall back to a mock if you confirm that the server is genuinely unreachable outside this session.

If a mock is required, state that explicitly before implementing it.

The prompt holds the server URL and the header names, never your credentials.

Try it here first

You are signed in, so the MCP tools tab's Execute runs any tool live against your organisation. Use it to see a real response before you build anything.

Start building against the NCC MCP server with a prompt. Give it to Claude Code (or your AI coding assistant) and it builds a working app that calls the live server — there is no separate REST integration to write.

Start the development

Copy the prompt below.
Replace the part in <angle brackets> with what you want to build, and change the example workflow to your own steps.
Open Claude Code (or another AI coding assistant) in an empty project folder and paste it.
When it asks for credentials, put your client ID and secret in the project's .env file yourself — never in the chat.
Run the app. The assistant checks its work by using it in the browser, against the live server.

prompt — copy into your assistant

# Prompt: Building a live Perse NCC MCP connector demo

Build a <sample UI app / demo: describe what you want, for example "a small web app"> for the Perse NCC MCP connector.

Workflow (an example: replace it with your own steps):

1. Create a file-drop link for the user to upload a half-hourly consumption CSV (ncc_file_drop_create) and wait for the upload (ncc_file_drop_wait).
2. Start a non-commodity cost calculation for a full MPAN and date range using that upload (ncc_transform_calculate_csv).
3. Poll the run until it finishes (ncc_transform_status).
4. Offer the result download (ncc_transform_download_url).

## MCP Server Verification

Before writing any mock/backend code, check whether the NCC connector is a real, publicly reachable MCP server using Streamable HTTP (plain JSON-RPC over POST), rather than assuming it only works inside this chat session.

Its endpoint is:

`https://ncc-mcp.perse.io/alpha/mcp`

Use exactly this URL: the bare `/mcp` path is retired and answers 410. Confirm the server is reachable with a plain `initialize` POST. Without credentials it answers 401 ("needs your organisation's client credentials"). That confirms the server is live and speaking MCP, so treat it as success for this check, not as a failure.

If the server responds:

- Wire the app to call the MCP server live, directly.
- Use a thin browser-side JSON-RPC client.
- Track the `mcp-session-id` response header.
- Route MCP requests through a same-origin dev-server proxy (for example Vite's `server.proxy`) to avoid CORS.
- Do **not** build an Express/mock backend for this.

## How the protocol works

- A session is: `initialize`, then `notifications/initialized`, then any number of `tools/list` and `tools/call`, each carrying the `mcp-session-id` header that `initialize` returned.
- Send `content-type: application/json` and `accept: application/json, text/event-stream`.
- Replies arrive as Server-Sent Events: read the `data:` line of each.
- A successful tool call returns its data in `result.structuredContent`. A failure has `result.isError: true` and a plain-language message in `result.content`.
- Discover the tools and their input schemas with `tools/list`. Do not guess tool names or arguments.

## Authentication

Credentials go on every request as these headers:

    x-ncc-client-id: <CLIENT_ID>
    x-ncc-client-secret: <CLIENT_SECRET>

Read the values from environment variables (PERSE_CLIENT_ID and PERSE_CLIENT_SECRET) in the dev server, and have the same-origin proxy add the headers, so the secret never reaches browser code, is never committed, and is never pasted into this chat. Create a `.env.example` with the variable names only.

Do not test authenticated tool calls with raw `curl`, as that gets blocked as bypassing the sanctioned tool interface.

Verify authenticated flows only by:

- actually using the running app in the browser, or
- using your own MCP tool calls.

## Existing Implementations

Before building from scratch, check for an existing reference implementation, such as other demo folders on disk.

Only fall back to a mock if you confirm that the server is genuinely unreachable outside this session.

If a mock is required, state that explicitly before implementing it.

The prompt holds the server URL and the header names, never your credentials.

Try it here first

You are signed in, so the MCP tools tab's Execute runs any tool live against your organisation. Use it to see a real response before you build anything.

Start building against the Switch MCP server with a prompt. Give it to Claude Code (or your AI coding assistant) and it builds a working app that calls the live server — there is no separate REST integration to write.

Start the development

Copy the prompt below.
Replace the part in <angle brackets> with what you want to build, and change the example workflow to your own steps.
Open Claude Code (or another AI coding assistant) in an empty project folder and paste it.
When it asks for credentials, put your client ID and secret in the project's .env file yourself — never in the chat.
Run the app. The assistant checks its work by using it in the browser, against the live server.

prompt — copy into your assistant

# Prompt: Building a live Perse Switch MCP connector demo

Build a <sample UI app / demo: describe what you want, for example "a small web app"> for the Perse Switch MCP connector.

Workflow (an example: replace it with your own steps):

1. Search addresses by postcode (domestic_switch_address_search).
2. Show the meters at the chosen address (domestic_switch_meter_details).
3. Generate switching quotes and show the cheapest first (domestic_switch_generate_quotes). Stop at quotes: completing a switch creates a real one.

## MCP Server Verification

Before writing any mock/backend code, check whether the Switch connector is a real, publicly reachable MCP server using Streamable HTTP (plain JSON-RPC over POST), rather than assuming it only works inside this chat session.

Its endpoint is:

`https://switching-mcp.perse.io/alpha/mcp`

Use exactly this URL: the bare `/mcp` path is retired and answers 410. Confirm the server is reachable with a plain `initialize` POST. Without credentials it answers 401 ("needs your organisation's client credentials"). That confirms the server is live and speaking MCP, so treat it as success for this check, not as a failure.

If the server responds:

- Wire the app to call the MCP server live, directly.
- Use a thin browser-side JSON-RPC client.
- Track the `mcp-session-id` response header.
- Route MCP requests through a same-origin dev-server proxy (for example Vite's `server.proxy`) to avoid CORS.
- Do **not** build an Express/mock backend for this.

## How the protocol works

- A session is: `initialize`, then `notifications/initialized`, then any number of `tools/list` and `tools/call`, each carrying the `mcp-session-id` header that `initialize` returned.
- Send `content-type: application/json` and `accept: application/json, text/event-stream`.
- Replies arrive as Server-Sent Events: read the `data:` line of each.
- A successful tool call returns its data in `result.structuredContent`. A failure has `result.isError: true` and a plain-language message in `result.content`.
- Discover the tools and their input schemas with `tools/list`. Do not guess tool names or arguments.

## Authentication

Credentials go on every request as these headers:

    x-switch-client-id: <CLIENT_ID>
    x-switch-client-secret: <CLIENT_SECRET>
    x-switch-utm-source: <TPI_SOURCE>

Read the values from environment variables (PERSE_CLIENT_ID, PERSE_CLIENT_SECRET and PERSE_TPI_SOURCE) in the dev server, and have the same-origin proxy add the headers, so the secret never reaches browser code, is never committed, and is never pasted into this chat. Create a `.env.example` with the variable names only.

Do not test authenticated tool calls with raw `curl`, as that gets blocked as bypassing the sanctioned tool interface.

Verify authenticated flows only by:

- actually using the running app in the browser, or
- using your own MCP tool calls.

## Existing Implementations

Before building from scratch, check for an existing reference implementation, such as other demo folders on disk.

Only fall back to a mock if you confirm that the server is genuinely unreachable outside this session.

If a mock is required, state that explicitly before implementing it.

The prompt holds the server URL and the header names, never your credentials.

Try it here first

You are signed in, so the MCP tools tab's Execute runs any tool live against your organisation. Use it to see a real response before you build anything.

Sign in