Cursor cloud agents

Loading version...

Port's Cursor Cloud Agents integration surfaces your Cursor cloud agents and their runs in your Context Lake. From there, you can launch new agents or send follow-up prompts to existing ones directly from Port workflows.

Supported resources agentrun

Core support

Live eventsSee supported resources

Trigger a Cursor cloud agent

Use this workflow to send a follow-up prompt to an existing Cursor cloud agent. See the Cursor Cloud Agents integration action page for the full node field reference.

Create a Cursor cloud agent

Use this workflow to let platform engineers or developers launch a new Cursor cloud agent through a self-service form. See the Cursor Cloud Agents integration action page for the full node field reference.

Create also launches a run

Launching a new Cursor cloud agent always starts a run and billable work immediately. See Action semantics on the integration action page for details.

Prerequisites

• A Cursor API key with access to the Cloud Agents API.
• Optionally configure a webhook signing secret (webhookSigningSecret) to verify incoming Cursor webhooks. The value must be at least 32 characters. Generate a random string with openssl rand -hex 32 and provide it during installation. When unset, webhook signature verification is skipped.
• Your Port user role is set to Admin.

Use a service account key

On the Cursor Enterprise plan, you can use a service account API key as the integration's cursor_api_key instead of a personal key. Runs are then attributed to the service account rather than an individual, so the integration keeps working as people and roles change. This requires the Cursor GitHub app to be connected at the team level with the target repositories authorized, and usage bills to your team's usage pool. Note that a service account key cannot reuse a user's saved MCP OAuth logins.

Setup

Choose one of the installation methods below. If you are not sure which option to use, review the installation methods overview.

Choose method

Configuration

Port integrations use a YAML mapping block to ingest data from the third-party API into Port.

The mapping uses the JQ JSON processor to transform fields and shape incoming Cursor data into Port entities.

Resource selectors

In addition to query, each resource supports optional selector fields in your Port App config:

Resource	Field	Default	Description
agent	includeArchived	false	Include archived agents from Cursor's List Agents API.
run	includeArchived	false	Include archived agents when fanning out to List Runs (Cursor has no separate archived filter on List Runs).
run	enrichRunsWithUsage	true	Fetch token usage per agent and merge it into each run during sync. Set to false to skip usage API calls.
run	oldestRunDate	unset	ISO 8601 UTC timestamp. Stop paginating runs for each agent once a run older than this cutoff is reached (runs are newest-first).

Example with a run sync window and usage enrichment disabled:

resources:
  - kind: agent
    selector:
      query: 'true'
      includeArchived: false
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"cursor_agent"'
  - kind: run
    selector:
      query: 'true'
      includeArchived: false
      enrichRunsWithUsage: false
      oldestRunDate: "2026-01-01T00:00:00Z"
    port:
      entity:
        mappings:
          identifier: .id
          title: .id
          blueprint: '"cursor_run"'

Webhook configuration

Cursor's v0 API attaches a webhook per agent at launch time - there is no account-wide webhook subscription to configure in a Cursor console. On create_agent, set apiVersion to v0 and reportCompletion to true; the integration then attaches a static callback URL as the agent's webhook when it launches it. trigger_agent follow-ups always use the v1 API but still receive completion callbacks on agents that were v0-created with a webhook.

<base_url>/integration/webhook

Where <base_url> is:

• Hosted by Port: the live events base URL shown in the install step above.
• Self-hosted: the liveEvents.baseUrl you configured during installation.

Optionally configure webhookSigningSecret on the integration (a sensitive installation setting). When set, it must be at least 32 characters. That value is sent to Cursor as the webhook secret and used to validate the X-Webhook-Signature header on incoming webhooks. When unset, signature verification is skipped.

Recommended for production

Configure webhookSigningSecret so incoming webhooks are authenticated. Without it, any caller that knows your callback URL can post status updates. Use at least 32 characters. openssl rand -hex 32 produces a 64-character value that meets Cursor's requirement.

Generate a value with for example:

openssl rand -hex 32

Store it as an organization secret during SaaS installation, or set OCEAN__INTEGRATION__CONFIG__WEBHOOK_SIGNING_SECRET for self-hosted deployments.

Default mapping configuration

Default mapping configuration (click to expand)

resources:
  - kind: agent
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"cursor_agent"'
          properties:
            status: .status
            url: .url
            repoUrls: |
              [.repos[]?.url // empty]
              | map(select(. != null and . != ""))
              | map(if startswith("http") then . else "https://" + . end)
              | map(select(test("^https?://.+")))
            createdAt: .createdAt
            updatedAt: .updatedAt
  - kind: run
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .id
          blueprint: '"cursor_run"'
          properties:
            status: .status
            durationMs: .durationMs
            branches: '[.git.branches[]?.branch | select(. != null and . != "")] // []'
            prUrls: '[.git.branches[]?.prUrl? | select(. != null)] // []'
            inputTokens: .usage.inputTokens
            outputTokens: .usage.outputTokens
            cacheReadTokens: .usage.cacheReadTokens
            cacheWriteTokens: .usage.cacheWriteTokens
            totalTokens: .usage.totalTokens
            createdAt: .createdAt
            updatedAt: .updatedAt
          relations:
            agent: .agentId

Mapping & examples per resource

To view and test the integration mapping against sample API responses, use the jq playground in your connectors page.

Run token usage

Cursor's List Runs and Get Run endpoints don't return token usage inline. When enrichRunsWithUsage is true (the default), the integration makes one extra request per agent to Cursor's usage endpoint and merges each run's usage into its payload before mapping, so the usage field shown in the sample payload below isn't present in Cursor's own List Runs response. Set enrichRunsWithUsage to false on the run resource to skip those calls.

Monitoring and sync status

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.