API Reference

Base URL: https://mcp.dariocositore.com

Authentication

Two methods:

Admin Key: Authorization: Bearer <ADMIN_KEY> -- full access
JWT: Authorization: Bearer <JWT> -- user-scoped access

Public Endpoints

GET /connectors/public

List all public connectors with metadata.

curl https://mcp.dariocositore.com/connectors/public

GET /

Health check. Returns server status, version, connector count.

Auth Endpoints

POST /auth/register

Create a new account. Body: email, password, display_name

curl -X POST https://mcp.dariocositore.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secure123","display_name":"user"}'

POST /auth/login

POST /auth/refresh

Refresh access token. Body: refresh_token

GET /auth/me

Get current user profile. Requires JWT.

MCP Endpoints

GET /{connector_id}/sse

Legacy SSE stream for a specific connector.

POST /{connector_id}/mcp

Streamable HTTP endpoint (modern). Send JSON-RPC body.

curl -X POST https://mcp.dariocositore.com/dario_hub/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Connector Schema

{
  "connector_id": "amazon-com",
  "connector_name": "Amazon.com",
  "description": "Search products, add to cart",
  "source_url": "https://www.amazon.com",
  "requires_oauth": false,
  "tools": [
    {
      "name": "amz_search",
      "description": "Search Amazon products",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      },
      "dom_steps": [
        { "action": "navigate", "url": "https://www.amazon.com" },
        { "action": "fill", "selector": "#twotabsearchtextbox", "param": "query" },
        { "action": "click", "selector": "#nav-search-submit-button" },
        { "action": "wait", "timeout_ms": 3000 }
      ]
    }
  ]
}

Execution Engine Action Capabilities

The execution engine currently supports 31 executable actions inside dom_steps. They are executed server-side via Playwright.

Navigation & Page Control

Action	Required Fields	Notes
`navigate`	`url`	Supports `{param}` substitution in the URL.
`wait_for_navigation`	—	Waits for `networkidle`.
`wait_for_selector`	`selector`	Waits until the element is visible.
`wait_for_network_idle`	—	Best smart-wait for single-page applications (SPAs).
`wait_for_text`	`text`	Waits for the specified text anywhere on the page.
`wait`	`timeout_ms`	⚠️ Hard-capped at 5 seconds (5000ms) server-side.

Interaction

Action	Required Fields	Notes
`fill`	`selector`, `param`	Self-healing element selector: automatically falls back to secondary selector formats or semantic text matches if the primary fails.
`click`	`selector`	Applies the same self-healing logic as `fill`.
`execute_js`	`script`	Evaluates raw JavaScript inside the page context. Supports `{param}` substitution.
`upload_file`	`file_path`, `selector`	⚠️ Files must already reside on the server's filesystem. Does not accept client-side file uploads directly.
`download_file`	`selector`	Triggers and captures file download; returns the resulting filename/path in the response.

Selector-Free Interaction Phase 4 (Vision)

Action	Required Fields	Notes
`vision_click`	`description`	Finds elements to click using semantic descriptions (e.g., text content, accessible roles, labels, or placeholders). No CSS selector required.
`vision_fill`	`description`, `param`	Fills input fields using semantic and description-based matching.
`vision_extract`	`description`	Extracts layout and page text content matching the semantic description.

Extraction & Output

Action	Required Fields	Notes
`extract`	`selector`, `as`	Extracts the element's inner `textContent` and returns it within the output object under the key assigned to `as`.
`screenshot`	—	Captures a current screenshot and returns it as a base64-encoded PNG under `result.screenshot`.

Session & Auth

Action	Required Fields	Notes
`save_session`	—	Saves cookies and localStorage variables. Active only if `session_mode` is set to `persistent` or `isolated`.
`restore_session`	—	Restores the cached browser state and authentication cookies for the connector scope.
`require_login`	`service`	Halts current steps and queries the AI agent client to request user credentials if no credentials exist in storage.
`auto_login`	`service`, `username_selector`, `password_selector`	Retrieves login credentials from your secure vault and populates the username and password elements.

Control Flow

Action	Required Fields	Notes
`label`	`name`	Creates an execution marker (serves as a no-op at execution time).
`goto`	`target`	Jumps programmatically to a predefined `label`. ⚠️ Total iterations are capped at `length(steps) × 10` to prevent endless loops.
`if_exists`	`selector`	Conditional check. Jumps execution directly to the matching `endif` if the selector element cannot be resolved.
`if_value`	`param`, `expected`	Conditional check. Jumps directly to the matching `endif` block if the parsed value of the `param` is not equal to `expected`.
`endif`	—	Closes a conditional sequence block.

Multi-Tab

Action	Required Fields	Notes
`new_tab`	—	Spawns a new viewport instance in the browser execution frame and shifts control focus directly to it.
`switch_tab`	`tab_index`	Switches active control focus using a 0-based tab index.
`close_tab`	`tab_index`	Closes the corresponding tab index. Cannot be used to close the final remaining active tab viewport.

Connector Chaining Phase 3

Action	Required Fields	Notes
`call_mcp`	`connector_id`, `tool_name`	Invokes a sub-tool belonging to another connector on the local platform server context.
`call_mcp_external`	`url`, `tool_name`	Executes a request targeting external, third-party MCP endpoints via HTTP.
`call_mcp_batch`	`calls` (array)	Runs multiple parallel connector calls and aggregates the resulting response objects before proceeding.

Known Limitations & Gotchas

File Upload Restrictions: The upload_file action is non-functional for standard user file uploads since it requires targeted files to already reside directly inside the backend server host file directory.
Wait Timing Threshold: The wait action is limited to a maximum threshold of 5 seconds server-side. For long periods of waiting, utilize smart-wait mechanisms like wait_for_network_idle.
Jump Loops: goto + label execution pathways are monitored to block infinite runtime loops. Loop limits are mathematically calculated and capped at len(steps) × 10. Exceeding this triggers a hard execution crash.
Conditional Closures: Using the if_exists or if_value statements without establishing an ending endif block will cause unhandled syntax errors during action step parsings.
Parameter Misalignments: Declaring a target variable inside fill that is absent from the tool’s declared inputSchema schema translates to an empty string input without prompting error codes.
Unrecognized Keywords: Declaring an unrecognized action identifier inside the workflow steps will bypass execution of that step without throwing compile errors.