# Dashport — full agent reference

## What it is
Dashport builds declarative web and mobile admin panels on top of an existing HTTP/JSON API. It provides accounts, project definitions, panel drafts, signed releases and management metadata. The shared mobile client can contain more than one Dashport. Customer record reads and writes run directly from the client to the customer API, not through a Dashport CRUD proxy.

Good fit: existing API, CRUD, forms, relationship lookups, KPI/charts, operational screens and mobile administration.
Not a fit without additional backend work: direct SQL access, data warehouse/ETL, arbitrary custom runtime code, inaccessible private APIs, unsupported authentication or an upstream requiring a confidential server-only secret in a public client.

## Public entry points
Home: https://dashport.org/
Human/agent documentation: https://dashport.org/developers
Discovery JSON: https://dashport.org/.well-known/dashport.json
MCP schemas: https://dashport.org/developers/mcp-tools.json
Panel schema: https://dashport.org/developers/panel.schema.json

## Connect
Transport: MCP Streamable HTTP.
New account endpoint: https://dashport.org/mcp/onboarding
Existing account endpoint: https://dashport.org/mcp/dashport
Existing-account authorization: OAuth with PKCE or a project-scoped MCP bearer key. A Dashport platform login token is not a valid MCP key.
OAuth server discovery: https://dashport.org/.well-known/oauth-authorization-server
Protected-resource discovery: https://dashport.org/.well-known/oauth-protected-resource/mcp/dashport

Example URL-based client configuration; adapt to the MCP client's format:
{
    "mcpServers": {
        "dashport-signup": {
            "url": "https://dashport.org/mcp/onboarding"
        }
    }
}

An agent needs an actual MCP connection; reading this document does not configure a client or authorize an account operation.

## New-account workflow
1. Obtain the user's request to create an account. Collect name, email and a new Dashport password. register_account requires name, email, password. Password minimum: 12 characters. Maximum: 72 bytes in backend validation. Do not reuse the customer backend password.
2. Call register_account. Retain signup_token privately. If email_sent is true, tell the user the exact returned email and ask them to relay the six-digit code from that email. If email_sent is false, report delivery failure; do not claim the message was delivered.
3. Wait for the user. Never guess codes or request mailbox access. Call verify_email with signup_token and the user-provided code.
4. Only after verified:true, call create_project with signup_token, name, visibility. Prefer private unless the user requests otherwise. Retain the returned project_id and environment_id.
5. Call context/schema/examples/capabilities tools; configure and validate the draft using the same connection. Non-publishing project tools on the onboarding server require signup_token in addition to their normal arguments.
6. Setup expires one hour after registration. It permits only one project and read/draft-edit scopes. It cannot publish. Switch to an appropriately authorized protected MCP connection for ongoing access or publication.

Verification code: six digits, 10-minute expiry, five failed attempts, single-use.
Resend tool: resend_verification_code(signup_token). Original email only. 60-second cooldown. At most five deliveries in the one-hour setup window. Replacement invalidates the previous code.
No verification code is returned by MCP. An email code alone is not a session credential; the private signup_token is required too.
Existing email: use the protected OAuth flow rather than attempting another registration.

## Panel construction workflow
- Inspect the actual customer's API. Establish API origins, request methods/paths, headers, login and refresh response mappings, pagination, search/filter parameters, identity IDs and permission signals. Do not invent endpoints or response shapes.
- Read get_context, get_capabilities, get_schema_reference, get_component_catalog and get_examples.
- Create a project if allowed. The bootstrap create_project grant is consumed and bound to that project on creation.
- Define connections, operations, resources/fields, views, rules, actions, permissions, settings and navigation using the actual schema.
- Configure lookup operations, paging/search or filters as appropriate. Define widget data operations and response mappings. A chart's data must be mapped; arbitrary APIs do not automatically match a dashboard.
- Save the complete definition with save_draft or use section upserts. Include expected_revision on mutations and use the latest revision.
- validate_panel checks the schema. preview_panel is only a static schema summary, not a rendered UI or live customer API test. Inspect diff_panel and verify behavior in a target client.
- On a publish-scoped protected connection, create_version freezes a draft. publish_panel requires explicit user intent and expected release revision. Signup tools never grant publication permission.
- For a usable mobile panel, add/select its Dashport in the common client after an authorized publication. Users can manually adjust panels in the mobile editor or web console at https://dashport.org/console.

## Data, trust and compatibility
- The customer backend enforces authentication and all field/module/record read and write authorization. UI visibility alone is not access control.
- Configure supported customer login, token/refresh or OTP flows. Optional registration/recovery endpoints may be omitted. Public panels need not require provider login.
- Keep credentials in protected per-user client session storage. Do not put real bearer tokens, passwords, signing keys or signup_token in a panel definition, generated code example or public log.
- A server-only secret requires a suitable authenticated endpoint on the customer's own backend. Dashport is not a safe mechanism to distribute confidential machine credentials to a web/mobile client.
- Use valid HTTPS for production customer APIs. Web clients also need correct CORS. The target device must be able to reach the API.
- Panel releases use signatures checked against client trust keys. Only predefined components and bounded declarative actions are supported; no arbitrary downloaded code. This is not an app-store review guarantee.
- Schema vocabulary is not the installed runtime capability set. Check get_capabilities, requiredCapabilities and target-client compatibility. Do not assume all catalog types (for example scatter) render on every client.
- Current contract limits: maxBytes=1048576, maxDepth=32, maxRuleDepth=8, maxActionSteps=16, maxConcurrentRequests=6, defaultTimeoutMs=30000.

## Errors
- email_sent:false: keep signup_token, inform the user and retry resend after cooldown.
- invalid_verification_code / verification_attempts_exceeded / verification_code_expired: ask for a valid/new code and follow limits; do not guess.
- signup_session_expired / signup_session_revoked: stop using the setup credential; registered users authenticate via OAuth.
- invalid_arguments: inspect argument schemas and reported field names. An existing email uses the existing-account flow.
- draft_conflict: fetch the current draft, inspect/reconcile changes and use the current revision. Do not overwrite blindly.
- Permission failure: inspect role and scope. Do not escalate permission or change visibility to bypass it.

## Available account tools
### register_account
Create a NEW Dashport account only when the user asks to sign up. Sends a verification code to that email immediately. Tell the user the exact recipient email and ask them to relay the code; call verify_email with their code. Do not claim verification or create projects before success. Existing users must use the protected /mcp/dashport OAuth login. Never log the password or put it in panel schemas.
Required: name, email, password
### verify_email
Verify the 6 digit code the user relays from the Dashport signup email. Never guess a code or request mailbox access. Unlocks one-project draft creation in this MCP connection; no publish permission.
Required: signup_token, code
### resend_verification_code
Send a replacement signup verification code to the original account email after at least 60 seconds. Invalidates the old code. At most five deliveries per hour. Tell the user to relay the new code.
Required: signup_token

## Available panel tools
The protected server filters tools by current role/grant. Onboarding exposes non-publishing panel tools with a required signup_token and verified setup session.
### get_context (mcp:read)
Read this key's project, organization and effective scopes.
Required: 
### get_capabilities (mcp:read)
Read contract limits. Vocabulary does not imply every mobile runtime implements it.
Required: 
### get_component_catalog (mcp:read)
Read the closed component vocabulary and JSON Schema.
Required: 
### get_schema_reference (mcp:read)
Read the complete panel JSON Schema. Never store customer secrets in a panel.
Required: 
### get_examples (mcp:read)
Read working starter panel definitions.
Required: 
### list_projects (mcp:read)
List only the project bound to this key.
Required: 
### create_project (mcp:create_project)
Create one project and permanently bind this bootstrap key to it.
Required: name, visibility
### get_draft (mcp:read)
Read current draft and revision.
Required: environment_id
### save_draft (mcp:write)
Save exact schema JSON with optimistic concurrency. Validation errors are returned; invalid drafts cannot be published.
Required: environment_id, expected_revision, schema_json
### upsert_connection (mcp:write)
Replace one connections entry in an existing JSON draft; definition_json is literal JSON, never executable code.
Required: environment_id, expected_revision, key, definition_json
### upsert_operation (mcp:write)
Replace one operations entry in an existing JSON draft; definition_json is literal JSON, never executable code.
Required: environment_id, expected_revision, key, definition_json
### upsert_resource (mcp:write)
Replace one resources entry in an existing JSON draft; definition_json is literal JSON, never executable code.
Required: environment_id, expected_revision, key, definition_json
### upsert_view (mcp:write)
Replace one views entry in an existing JSON draft; definition_json is literal JSON, never executable code.
Required: environment_id, expected_revision, key, definition_json
### upsert_action (mcp:write)
Replace one actions entry in an existing JSON draft; definition_json is literal JSON, never executable code.
Required: environment_id, expected_revision, key, definition_json
### upsert_rule (mcp:write)
Replace one rules entry in an existing JSON draft; definition_json is literal JSON, never executable code.
Required: environment_id, expected_revision, key, definition_json
### upsert_permission (mcp:write)
Replace one permissions entry in an existing JSON draft; definition_json is literal JSON, never executable code.
Required: environment_id, expected_revision, key, definition_json
### upsert_settings (mcp:write)
Replace one settings entry in an existing JSON draft; definition_json is literal JSON, never executable code.
Required: environment_id, expected_revision, key, definition_json
### upsert_dashboard (mcp:write)
Replace a dashboard view using the closed dashboard widget schema.
Required: environment_id, expected_revision, key, definition_json
### validate_panel (mcp:read)
Validate an exact draft revision locally.
Required: environment_id, expected_revision
### preview_panel (mcp:read)
Static schema summary only; does not render a client or call customer APIs.
Required: environment_id, expected_revision
### diff_panel (mcp:read)
Compare draft with a frozen version; return changed paths without values.
Required: environment_id, version_id
### create_version (mcp:write)
Freeze a validated draft revision.
Required: environment_id, expected_revision
### list_versions (mcp:read)
List immutable project history.
Required: environment_id
### list_releases (mcp:read)
List immutable project history.
Required: environment_id
### get_version (mcp:read)
Read a frozen version.
Required: environment_id, version_id
### publish_panel (mcp:publish)
Publish a frozen version as a signed release; explicit expected_release_revision prevents overwrites. Publish an earlier version to roll back.
Required: environment_id, version_id, expected_release_revision

## Canonical examples
These are shipped illustrative definitions, not live customer services. Adapt origins and API mappings to the user’s project. Validate before publication.
- https://dashport.org/developers/examples/advanced-crm.panel.json
- https://dashport.org/developers/examples/blank-canvas.panel.json
- https://dashport.org/developers/examples/canvas.panel.json
- https://dashport.org/developers/examples/crm.panel.json
- https://dashport.org/developers/examples/provider-auth.panel.json
- https://dashport.org/developers/examples/public-catalog.panel.json
- https://dashport.org/developers/examples/review-demo.panel.json
- https://dashport.org/developers/examples/runtime-crm.panel.json
- https://dashport.org/developers/examples/showcase-crm.panel.json

Full argument schemas: https://dashport.org/developers/mcp-tools.json