# Numsolar > Numsolar estimates solar PV output for Swedish roofs and gives solar installers access to their own prospects and offers. AI agents connect over MCP (Model Context Protocol): JSON-RPC 2.0, one POST per call. > Public tools give estimates, not quotes. Units: energy kWh, panel power kWp, angles in degrees, money SEK incl. VAT. Azimuth: 0 = north, 90 = east, 180 = south, 270 = west, clockwise. > Coordinates (lat, lng) are WGS 84 decimal degrees. For a Swedish town use its centre: the data grid is 0.25° × 0.5°, so a town centre is accurate enough for an estimate. get_started_link also takes a street address. > A key on /mcp gives all 10 tools: the organisation tools and the public ones. Full documentation: https://numsolar.com/docs/mcp ## Endpoints - [POST https://numsolar.com/mcp/public](https://numsolar.com/docs/mcp#endpoint-public): Public estimates (no key). Anonymous. Solar output estimates for any roof in Sweden, and a link where a homeowner continues. Uses only our own precomputed data: no account and no cost. We keep only a short call log, without the values you send. - [POST https://numsolar.com/mcp](https://numsolar.com/docs/mcp#endpoint-org): Your organisation's data (key needed). Needs an API key of your organisation. Read only: your prospects, offers, equipment and price templates, plus the public estimate tools. A key on /mcp gives all 10 tools, so your agent needs only this one server. A key never sees another organisation's data. ## Get a key (for /mcp) - [Open the settings page](https://numsolar.com/docs/mcp#key-step-1): Sign in to Numsolar as an admin of your organisation and open Settings › API keys for AI agents. - [Create a key](https://numsolar.com/docs/mcp#key-step-2): Click Create key. Give the key a name (for example "Our sales agent") and tick what it may read. - [Copy the key into your agent](https://numsolar.com/docs/mcp#key-step-3): Copy the key at once: we show it only once. Your agent sends it in the header Authorization: Bearer ns_live_XXXXXXXX_YOUR_SECRET_KEY. Revoke the key on the same page when you no longer need it. ## Key scopes - [prospects:read](https://numsolar.com/docs/mcp#scopes): Prospects: name, contact details, address, status (tools list_prospects, get_prospect). - [offers:read](https://numsolar.com/docs/mcp#scopes): Offers: status, system size, price incl. VAT, tax deduction (tools list_offers, get_offer). - [catalog:read](https://numsolar.com/docs/mcp#scopes): Catalogue: equipment and price templates (tools list_equipment, list_price_templates). - [prices:read](https://numsolar.com/docs/mcp#scopes): Internal cost and margin: adds purchase cost, margin and discount to the offer and equipment tools. Give it only to an agent you trust with your purchase prices. ## Tools - [estimate_yield](https://numsolar.com/docs/mcp#estimate_yield): (/mcp/public, also /mcp with a key) Estimate yearly and monthly PV output in kWh for one roof face in Sweden (nearby land in Norway, Denmark and Finland also gets a value, with lower accuracy). Returns kWh per kWp of panels (and total kWh when kwp is given), the best angle at the point and the data source. Angles in degrees: tilt_deg 0 = flat, 90 = vertical; azimuth_deg is a compass bearing, 0 = north, 90 = east, 180 = south, 270 = west (clockwise). An estimate, not a quote. lat and lng are WGS 84 decimal degrees; for a Swedish town its centre is accurate enough (the data grid is 0.25° × 0.5°). - [estimate_roof_faces](https://numsolar.com/docs/mcp#estimate_roof_faces): (/mcp/public, also /mcp with a key) Estimate the total yearly and monthly PV output in kWh for a house with 1 to 8 roof faces in Sweden, and the output of each face. Each face has tilt_deg (0 = flat, 90 = vertical), azimuth_deg (compass degrees: 0 = north, 90 = east, 180 = south, 270 = west, clockwise) and kwp (panel power in kWp). An estimate, not a quote. lat and lng are WGS 84 decimal degrees; for a Swedish town its centre is accurate enough (the data grid is 0.25° × 0.5°). - [yield_matrix](https://numsolar.com/docs/mcp#yield_matrix): (/mcp/public, also /mcp with a key) Return yearly PV output in kWh per kWp for every roof angle at one point in Sweden, and the best angle. Rows are tilts 0–90 degrees in 5-degree steps (0 = flat); columns are compass azimuths 0–350 degrees in 10-degree steps (0 = north, 90 = east, 180 = south, 270 = west, clockwise). Limited to 10 calls per clock minute; use estimate_yield for one angle. lat and lng are WGS 84 decimal degrees; for a Swedish town its centre is accurate enough (the data grid is 0.25° × 0.5°). - [get_started_link](https://numsolar.com/docs/mcp#get_started_link): (/mcp/public, also /mcp with a key) Return a Numsolar web link where the homeowner continues with a real roof model and installer quotes. Give address (a street address in Sweden), or lat and lng in degrees. It creates no account and starts no calculation. The link opens the Numsolar wizard with the address filled in. - [list_prospects](https://numsolar.com/docs/mcp#list_prospects): (/mcp, scope prospects:read) List your organisation's prospects (homeowners who may buy), newest change first, with name, city and status; use get_prospect for contact details and offers. - [get_prospect](https://numsolar.com/docs/mcp#get_prospect): (/mcp, scope prospects:read) Get one prospect of your organisation by id, with name, e-mail, phone, address and status, and its offers when the key may read offers. - [list_offers](https://numsolar.com/docs/mcp#list_offers): (/mcp, scope offers:read) List your organisation's offers, newest change first, with status, system size in kWp and price after the tax deduction in SEK incl. VAT; use get_offer for the details. - [get_offer](https://numsolar.com/docs/mcp#get_offer): (/mcp, scope offers:read) Get one offer of your organisation by id: status, package and items, system size in kWp, estimated yearly output in kWh, price after the tax deduction, the deduction and VAT in SEK incl. VAT, and the client's share link. - [list_equipment](https://numsolar.com/docs/mcp#list_equipment): (/mcp, scope catalog:read) List your organisation's equipment catalogue, newest change first, with panel power in W, battery capacity in kWh and inverter power in kW; the purchase cost needs the prices:read scope. - [list_price_templates](https://numsolar.com/docs/mcp#list_price_templates): (/mcp, scope catalog:read) List your organisation's price templates (the price rules an offer uses), newest change first, with status draft or active and currency. ## Limits - [Requests per IP address](https://numsolar.com/docs/mcp#limit-requests): 120 requests per clock minute on /mcp/public and 600 on /mcp, of any kind (also initialize, tools/list, ping and bad requests). Over that: HTTP 429 with Retry-After. - [Per IP address on /mcp/public](https://numsolar.com/docs/mcp#limit-public): 60 tool calls per clock minute and 1000 a day (UTC). yield_matrix: also at most 10 per clock minute. - [Per key on /mcp](https://numsolar.com/docs/mcp#limit-key): 120 tool calls per clock minute and 10000 a day (UTC), the public tools included (yield_matrix: also at most 10 per clock minute). Each key has its own count: your other keys keep working. - [Calls with a wrong key](https://numsolar.com/docs/mcp#limit-auth): 20 per clock minute per IP address. After that, a call from that address with a missing or wrong key gets HTTP 429 until the minute ends; a call with a valid key still works. - [Calls at the same time](https://numsolar.com/docs/mcp#limit-concurrency): 8 tool calls at once for the whole server. Over that, a call gets busy with retry_after_seconds. - [Request size](https://numsolar.com/docs/mcp#limit-body): 256 KB per request body. A larger body gets HTTP 413.