MCP reference
The remote endpoint and discovery-to-execution flow for ConvergeSense clients.
Transport and authentication
Use OAuth-protected Streamable HTTP at:
https://mcp.convergesense.com/mcp
Clients can discover metadata at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server on the MCP host. Complete browser consent for exactly one workspace.
Core tools
| Tool | Purpose |
|---|---|
convergesense_get_context | Read the selected workspace, granted permissions, and available tool count. |
convergesense_search_tools | Search approved tools available to the current grant. |
convergesense_describe_tool | Read one ready tool's reviewed input and query contract. |
convergesense_run_tool | Queue an approved read with exact inputs and an idempotency key. |
convergesense_get_job | Poll a job created by the same user, client, workspace, and grant. |
Search for a tool
The following is the argument object for convergesense_search_tools, passed through your MCP client:
{
"query": "port usage",
"limit": 10
}
Describe the contract
Use the exact tool_key returned by discovery. This placeholder must be replaced before calling convergesense_describe_tool:
{
"tool_key": "<discovered-tool-key>"
}
Run a read
convergesense_run_tool requires the discovered tool_key, the arguments specified by its contract, and an idempotency_key of 8–128 characters.
Optional selection fields include freshness (policy or live), bounded filters, selected fields, and a limit. The tool contract remains authoritative for supported queries. Do not infer accepted arguments from a different connector.
Poll the original job
Pass the returned UUID as job_id to convergesense_get_job. A pending response does not require a new execution. Normalized results remain readable for 15 minutes after completion.
Workflow tools
| Tool | Purpose |
|---|---|
convergesense_list_workflows | Find published tenant workflows. |
convergesense_describe_workflow | Read the pinned release and bounded step outline. |
convergesense_run_workflow | Start a reviewed workflow. |
convergesense_get_workflow_run | Read and advance coordination without replaying commands. |
convergesense_cancel_workflow_run | Cancel between steps. |
convergesense_list_automations | List owner-managed schedules visible to the grant. |
convergesense_trigger_automation | Run an enabled automation with its stored input template. |
Playbook tools
When operational playbooks are enabled, convergesense_search_playbooks and convergesense_get_playbook expose guidance and capability coverage.
Authorized owners with admin consent can also discover convergesense_create_playbook_draft, convergesense_update_playbook_draft, and convergesense_validate_playbook_draft. These mutate draft application state or validate it; they cannot publish or call equipment. See Operational playbooks.
Errors and retries
Keep the original job ID and idempotency key after timeouts. Expose warnings and incomplete coverage to the user. For a revoked grant, unavailable tool, offline Engine, or rate limit, follow the troubleshooting guide.