# Voltformer Agent API

> Machine identity and RFQ protocol for autonomous agents.

Visiting GPT, Claude, Gemini, Perplexity and other agents create a limited standalone identity with POST https://voltformer.com/api/v1/agents/self-register. The one-time secret is sent as `X-Voltformer-Agent-Key`. Standalone identities can read the catalog and submit independent RFQs but cannot access any member account, project, favorite or file. Member workspace operations require explicit OAuth 2.1 authorization from the human account owner. Inspect identity with GET https://voltformer.com/api/v1/agents/me. OpenAPI: https://voltformer.com/openapi.json - MCP: https://voltformer.com/mcp - Catalog: https://voltformer.com/agent-catalog.json


# Voltformer agent integrations

Canonical MCP endpoint: https://voltformer.com/mcp (Streamable HTTP). Public catalog, technical articles, material indices and engineering discovery need no account. Member data and drawings require account-owner authorization; an agent cannot acquire another user's workspace through standalone self-registration.

Voltformer is operated by Litequo LLC. Publisher and privacy contact: info@voltformer.com. The plugin package, agent catalog and SEO organization data use the same operator identity as the published privacy policy.

## OAuth and provider setup

- Resource discovery: https://voltformer.com/.well-known/oauth-protected-resource/mcp
- Authorization server: https://voltformer.com/.well-known/oauth-authorization-server
- Authorization: https://voltformer.com/oauth/authorize
- Token: https://voltformer.com/oauth/token
- Dynamic client registration: https://voltformer.com/oauth/register
- Revocation: https://voltformer.com/oauth/revoke (send the token plus the registered client ID/authentication method; confidential clients must authenticate)
- Resource indicator: `https://voltformer.com/mcp`
- Public MCP clients use authorization code + S256 PKCE. Register exact callback URLs. Access tokens expire after 15 minutes; refresh tokens rotate and expire after 30 days. Never put credentials in URLs.
- PKCE challenges must be the 43-character base64url SHA-256 digest. Verifiers must contain 43–128 unreserved characters. A client registered for authorization code only receives no refresh token. Consent requires a registered Voltformer account; anonymous Firebase sessions cannot authorize a connector.

ChatGPT plugins/MCP: add the canonical endpoint with OAuth. Discovery supports trusted OpenAI CIMD and DCR; tool descriptors publish security schemes and required scopes. Authentication failures provide both HTTP challenges and `mcp/www_authenticate` metadata. The provider account administrator must perform the actual connection and any directory submission.

Claude connectors: use the canonical HTTPS endpoint and OAuth. Both DCR and trusted Claude CIMD are supported. Transport authentication failures include the resource metadata URL. Claude API's remote MCP connector needs an OAuth access token obtained by the integrating application; merely adding the URL does not perform user consent.

Gemini: use the documented remote MCP integration or an MCP-capable SDK/CLI client. Configure `name: "voltformer"`, the canonical URL, and an `Authorization: Bearer ...` header for member operations. Token acquisition/refresh belongs to the integrating client. Do not assume the consumer Gemini chat UI supports arbitrary custom connectors.

GPT Actions: import https://voltformer.com/openapi.json and configure OAuth in the GPT editor. The documented confidential Actions flow differs from MCP: it may omit PKCE/resource. An operator can configure a dedicated confidential entry in `VOLTFORMER_OAUTH_CLIENTS` with `allowLegacyGptActions: true`, a securely generated client secret, and the exact `https://chatgpt.com/aip/g-.../oauth/callback` (or `chat.openai.com`) URL. This exception cannot be requested through dynamic registration and does not weaken public MCP PKCE requirements. Requires the real GPT ID and client configuration; publishing a discovery file alone does not install or approve a plugin.

## Production endpoint versus provider publication

The endpoint above is the shared production service, not a local development tunnel. A working endpoint or legacy discovery manifest does not mean an approved public ChatGPT/Claude directory listing. Provider publication and signed-in cross-provider verification have not yet been confirmed. See the [OpenAI submission requirements](https://developers.openai.com/plugins/deploy/submission) and [Claude directory requirements](https://claude.com/docs/connectors/building/submission). Organization administrators control provider-side installation and availability.

`/oauth/userinfo` currently requires `profile:read`. Its `email_verified` value comes from the verified Firebase token claim, not merely the presence of an email address. Old grants without that claim return false until reconnection. This service does not support full OpenID Connect or OpenAI workspace email-domain restrictions. `/.well-known/openid-configuration` returns 404; clients must use the OAuth authorization-server discovery URL above.

## SLD workflow

1. Call `getSldCapabilities` for the symbol library, template and complete example snapshot.
2. Read/create a project with `listProjects` / `upsertProject`.
3. Call `createSldDocument` with a stable `sldId`, project and template (`blank`, `substation`, `solarBess`, `dualIncomer`). Reconcile a retried creation with `getSldDocument`.
4. Read the full document. Edit positions, rotations, equipment properties, terminal connections, busbars, sheets, text/shape annotations and saved study settings. Send the entire preserved snapshot to `saveSldDocument` with the last `storageVersion` as `expectedVersion`. A conflict requires re-reading and reconciling edits.
5. `linkSldCatalogProduct` validates the exact selected product and synchronizes the same manufacturer properties as the editor. `syncSldProjectEquipment` merges the take-off into project equipment.
6. `analyzeSldDocument` runs the shared editor study delivery. `runSldStudy` exposes N-1 contingency screening, individual/concurrent/scheduled motor starts, classical swing, explicit sequence-fault calculations and protection tolerance sweeps. Examine validation, readiness, assumptions and unavailable-study reasons. Numerical output does not constitute engineering approval.
7. `exportSldDocument` returns SVG/DXF/JSON, PNG/PDF (base64), pandapower Python, BOM/cable CSV or study HTML/JSON. Rendered images use bundled local fonts. No diagram or account data is published to the public catalog.
8. `createSldRevision` archives a versioned snapshot; `listSldRevisions`, `duplicateSldDocument` and `deleteSldDocument` support the document lifecycle. Deletion retains revisions. Ask the user before changing approval status or deleting a drawing.

Read operations use `project:read`; modifications use `project:write`. Existing tools use their documented profile, favorites, RFQ and specification scopes. These tools delegate ordinary member workflows, not administrator privileges or unrestricted access to other accounts. Private diagrams appear in the same project workspace at https://voltformer.com/my-projects.

## Discovery and search

Version 3.6.0 exposes 63 MCP tools and three prompts. Public discovery covers six equipment families: transformers, switchgear, protection/control, generators, grid equipment and solar modules. Use `querySolar` / `getSolarBySlug` for panels; PV inverters are in `queryGridEquipment` / `getGridEquipmentBySlug`. Brand counts and samples cover all six families. Transformer calculations apply to transformers, not other equipment ratings.

`mcp.json` and OpenAPI tool operations are generated from the deployed MCP registry. Generic `POST /api/v1/tools/execute/{toolName}` responses use the same object contract as MCP `structuredContent` and JSON text content. Existing REST collection routes such as `/api/v1/brands` retain their documented array format. OpenAPI declares the complete OAuth scope set and supported OAuth/key alternatives for member REST operations. Plugin package, manifests and server versions must agree before build succeeds.

`llms.txt` and Markdown supplements aid discovery by clients that read them; they are not a ranking guarantee or a substitute for HTML. Google [does not use llms.txt](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide). Public sitemap routes have localized initial HTML, canonical/hreflang metadata and structured data. Catalog/reference Markdown supplements are shared English copies; engineering tool guides also have localized Markdown. Crawlers receive the same initial HTML as users. Private workspace contents are never prerendered.

Public market-data tools may fetch configured external World Bank, Eurostat or currency-rate endpoints and declare `openWorldHint: true`. Electricity lookups also declare initialization writes to the shared price store. These annotations do not grant access to private project data.

## Official references checked 2026-10-01

- OpenAI authentication: https://developers.openai.com/plugins/build/auth
- GPT Actions authentication: https://developers.openai.com/api/docs/actions/authentication
- Claude authentication: https://claude.com/docs/connectors/building/authentication
- Gemini function calling / remote MCP: https://ai.google.dev/gemini-api/docs/function-calling
- MCP authorization: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
- MCP Streamable HTTP: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
- PKCE syntax: https://www.rfc-editor.org/rfc/rfc7636
- Token revocation: https://www.rfc-editor.org/rfc/rfc7009
- Google AI features and SEO: https://developers.google.com/search/docs/appearance/ai-features
- Google AI optimization: https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
- OpenAI crawler policies: https://developers.openai.com/api/docs/bots