AI Assistants

What an assistant can do

Connected to your account, an assistant works on your projects at your request. It calls the tools below and tells you what it did; you never type a tool's name yourself. It cannot change your account, users or billing, and cannot delete projects.

What you need

A pvSpline account with an active plan.

The one you sign in to in the web app. The assistant works inside that account, with its projects and its monthly allowances: the engine time its simulations use and the cloud API time its requests take. No account yet? Signing in says how one is created, and Plans and what they unlock describes the plans.

AI assistants on for your company.

A new company starts with them off; a Manager account turns them on (Turning assistants on for your company).

A computer in France.

pvSpline accepts connections from France only, so the assistant must run on your computer, in France.

Turning assistants on for your company

AI assistants must first be on for your company. A Manager account turns them on, for every member at once, by ticking AI assistants under Service tokens, below the server and CI box; the card then says what an assistant sends to its provider and which plan to prefer with it. A new company starts with them off. While they are off, the consent page refuses to connect an assistant, and an assistant already connected, or using an assistant token, is refused until they are on again.

Every other member reads which way the switch is set. Unticking it asks for confirmation first: every assistant connected to a colleague's account stops working. The connections are kept, and work again once assistants are back on.

Connecting an assistant

Every client takes the same server address:

https://api.pvspline.fr/mcp

The entry for your client (The entry for your client) gives that address and nothing else: the first time the assistant calls pvSpline, it asks you to sign in.

Each connection then appears under Service tokens, named after the assistant with (OAuth); Revoke disconnects it. Access lasts an hour and renews itself while the assistant is in use, and a connection left unused for 90 days asks you to sign in again. A connection counts towards your limit of active tokens; at the limit the page answers Your account has too many active tokens. Revoke one under Account → Service tokens, then try again.

The entry for your client

Commands and configuration files are the same in every language.

Claude Code.

One command in a terminal, then /mcp in Claude Code to sign in:

claude mcp add --transport http pvspline https://api.pvspline.fr/mcp

Cursor, Windsurf and other clients with an mcpServers file.

Add the pvspline entry to the file:

{
  "mcpServers": {
    "pvspline": {
      "url": "https://api.pvspline.fr/mcp"
    }
  }
}

VS Code.

In the workspace's .vscode/mcp.json:

{
  "servers": {
    "pvspline": {
      "type": "http",
      "url": "https://api.pvspline.fr/mcp"
    }
  }
}

The consent page (/oauth/consent)

The page the assistant opens asks before anything is connected: which assistant asks, for which account, where your browser goes next, and what the assistant will and will not be able to do. Before Allow, it also says what the assistant's provider receives and what pvSpline never sends it (Your clients' data).

An assistant that cannot sign in

For an assistant that cannot sign in, mint an assistant token under Service tokens: type a name, choose AI assistant (MCP) in the scope list and press Create token. An assistant token only opens the AI-assistant endpoint, not the rest of your account. The token is shown once, like any service token (Your Account, Team & Cloud Runs). Setup guide, at the end of the hint that choice shows under the form, opens this chapter in a new tab, so the token stays on screen while you read.

Send the token in the Authorization: Bearer header: paste it in place of YOUR_MCP_TOKEN in the entry for your client.

A client that takes HTTP headers.

The same entry, with the token:

{
  "mcpServers": {
    "pvspline": {
      "url": "https://api.pvspline.fr/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

A client that only starts local commands.

The same entry, through mcp-remote:

{
  "mcpServers": {
    "pvspline": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.pvspline.fr/mcp",
        "--header",
        "Authorization:${PVSPLINE_AUTH}"
      ],
      "env": {
        "PVSPLINE_AUTH": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Your first request

Once the assistant is connected, ask it, for example:

“Estimate the yearly production of a 6 kWp roof facing south at 30° in Lyon, plus 3 kWp facing east. Show the monthly profile and the main losses.”

Some assistants ask you to approve an action the first time they use it.

Good to know

• Allowances. Each run an assistant starts needs an active plan and counts the engine time it uses against your monthly simulation allowance, exactly like a run started in the web app; the assistant can check what is left. Every request it makes counts against your cloud API allowance — your own on a subscription, the company's on the free plan — in seconds of server time. Past that allowance its calls are refused with the API_ALLOWANCE_EXCEEDED code until the 1st of the month (Monthly allowances by plan).

• The module. Projects are packed with a mainstream 425 W module unless you name another one. Open the project in the web app to draw the real roof, choose components, or use your meter's data.

• Savings and payback. Give the assistant your yearly consumption, your tariff or price per kWh, and the installation cost. It spreads the consumption with a standard profile (home, office, shop…) and uses 22:00–06:00 as off-peak hours for a peak/off-peak tariff.

• The figures. Results are P50/P90 estimates of the modelled system, from the same engine and weather the web app uses. Savings and payback use the cautious P90 yield unless the project says otherwise.

• The report. Its report, charts and workbook are written in English, whatever the interface language. Its PDF report carries no verification QR code (Report verification), unlike those of the runs you start in the web app.

• Enedis meters. A project whose consumption comes from an Enedis meter runs only from the web app, which can download the meter's data: the assistant can neither read, change, copy nor run it.

• Your open project. A change the assistant makes is a new version of the project. If you have that project open in the app, saving your version is refused rather than overwriting the assistant's (Working with projects).

Your clients' data

What the assistant reads goes to its provider — Anthropic, OpenAI or another — which processes it under its own terms, possibly outside the European Union: project names, their approximate location (to about a kilometre), arrays, consumption estimates, prices, costs and results. pvSpline never sends it your clients' names or addresses, Enedis meter data or your reports.

Your company decides: a new company starts with assistants off, and a Manager account turns them on or off for the whole company (Turning assistants on for your company).

For developers

Endpoint

https://api.pvspline.fr/mcp, over Streamable HTTP. It speaks protocol version 2026-07-28 and the earlier versions, negotiated at initialization.

Sign-in

OAuth 2.1 with dynamic client registration and PKCE. An access token lasts an hour and the client renews it; a connection unused for 90 days signs in again.

Token fallback

A token with the scope AI assistant (MCP), sent as Authorization: Bearer <token>, opens this endpoint and nothing else (An assistant that cannot sign in).

Discovery

The protected-resource metadata, https://api.pvspline.fr/.well-known/oauth-protected-resource/mcp; the server card, https://app.pvspline.fr/.well-known/mcp/server-card.json; https://app.pvspline.fr/llms.txt; and the server's name in the MCP Registry, fr.pvspline/pvspline.

The endpoint and its metadata answer requests from France only.