MCP FAQs
ON THIS PAGE
What is OpenSolar MCP?
OpenSolar MCP is a remote Model Context Protocol server that lets AI agents call OpenSolar tools on behalf of your organisation. Agents can list projects, update contacts, run auto-design, configure webhooks, and more, without writing custom API clients.
How is MCP different from the REST API?
| REST API | MCP | |
|---|---|---|
| Best for | Application integrations, backends, scripts | AI agents and MCP hosts |
| Auth | Bearer / machine-user tokens | OAuth (no pasted API bearer tokens) |
| Surface | Full documented HTTP endpoints | Tools that map to the same capabilities as the API, plus resources and prompts |
| Billing gate for data | API Access / Raw Data API Access | MCP Access + Raw Data for API-backed tools |
You can use both. Many MCP tools map to the same underlying org-scoped API routes.
Do I need API Access as well as MCP Access?
- MCP Access entitles the organisation to connect MCP. It is an OpenSolar service that organisation admins enable from the OpenSolar app.
- Raw Data API Access is required for tools that call OpenSolar API (everything except
whoami). - Partner API Access (Shrimp
s_/ SDK SKU) is a separate product for direct REST/SDK usage. MCP uses a first-party adapter credential and is not billed as that partner API Access SKU.
See API Access FAQs for Raw Data details.
Which MCP hosts are supported?
Gemini CLI, Claude Code, Codex, and Cursor are documented in Connect with Clients. Any MCP client that supports remote Streamable HTTP servers and OAuth can connect to https://mcp.opensolar.com/mcp. Behaviour may vary by client.
How do I connect a client?
See Connect with Clients. Add the production URL, authenticate, pick org and scopes, then ask the agent what it can do.
What scopes should I grant?
Grant the minimum needed:
- READ — explore projects, contacts, systems, configs
- WRITE — create/update records, run auto-design, generate documents
- DELETE — irreversible deletes
Can agents download private file bytes?
No. File tools return metadata only on read. Use OpenSolar UI or the REST private-files flow when you need binary content.
Are deletes reversible?
Destructive tools require DELETE and an explicit confirm=true. Treat them as irreversible. Prefer soft workflows (status updates) where possible.
How are rate limits applied?
Per-organisation daily weighted tokens and burst requests. Heavier or longer-running tools typically use more of the daily budget. For up-to-date values, visit Control → Integrations → MCP in the OpenSolar app. See MCP Limits. REST throttles still apply on underlying API routes.
Where can I see usage and revoke access?
Control → Integrations → MCP shows sessions (with scopes) and Overview usage. Admins see org-wide data; other users see their own. Revoking a session invalidates that client's refresh tokens.
Where is the full list of tools?
The Tools page is a non-exhaustive catalogue. For the most up-to-date list, please ask the agent.
Connection failed. Where do I start?
See Troubleshooting and Errors.