Claude managed agents

Loading version...

Port's Claude Managed Agents integration surfaces your Anthropic agents, environments, sessions, vaults, and memory stores in your Context Lake. From there, you can trigger agent sessions directly from Port workflows or let platform engineers create new agents through self-service forms.

Supported resources agentenvironmentsessionvaultmemory-storeskill

Trigger a Claude agent

Use this workflow to start a new session or continue an existing one, and send a user message to the agent. See the Claude managed agents integration action page for the full workflow JSON and node field reference.

GitHub repository resources

When a session includes a github_repository resource and githubAuthorizationToken is configured on the integration, the token is automatically injected so the session can clone and push to the repository. This works without the GitHub MCP server. To also open pull requests, the agent needs a vault with GitHub MCP credentials (see the MCP server setup section on the integration action page).

Create a Claude agent

Use this workflow to let platform engineers or developers create a new Claude managed agent through a self-service form. See the Claude managed agents integration action page for the full workflow JSON and node field reference.

MCP server setup

Agents can use Port MCP or GitHub MCP during sessions. Both require a Claude credential vault with the appropriate token. For the full credential setup steps, see MCP server setup on the integration action page.

Prerequisites

• An Anthropic API key.
• Your Port user role is set to Admin.

Setup

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

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 Claude data into Port entities.

Webhook configuration

To enable real-time updates from Claude to Port, configure a webhook in the Claude Console. The webhook endpoint URL follows the format:

<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.

To set up the webhook:

1. In the Claude Console, go to Manage > Webhooks and click Add webhook endpoint.
2. Paste the endpoint URL.
3. Under Events to subscribe, enable:
   • session.status_idled
   • session.status_terminated
   • vault.created
   • vault.archived
   • vault.deleted
4. Copy the signing secret shown at the end and set it as webhookSigningSecret in your integration settings.

Signature verification is optional

Configuring webhookSigningSecret is optional. When set, the integration validates the signature on every incoming webhook and rejects requests with an invalid or missing signature. When not set, incoming webhook requests are accepted without signature verification.

Default mapping configuration

Default mapping configuration (Click to expand)

resources:
  - kind: environment
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"claude_environment"'
          properties:
            description: .description
            scope: .scope
            environmentType: .config.type
            metadata: .metadata
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at
  - kind: vault
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .display_name
          blueprint: '"claude_vault"'
          properties:
            metadata: .metadata
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at
  - kind: memory-store
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"claude_memory_store"'
          properties:
            description: .description
            metadata: .metadata
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at
  - kind: skill
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: '.display_title // .id'
          blueprint: '"claude_skill"'
          properties:
            displayTitle: .display_title
            source: .source
            latestVersion: .latest_version
            createdAt: .created_at
            updatedAt: .updated_at
  - kind: agent
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"claude_agent"'
          properties:
            description: .description
            model: .model.id
            system: .system
            version: .version
            metadata: .metadata
            mcpServers: '[.mcp_servers[]?.name] // []'
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at
          relations:
            skills: '[.skills[]? | select(.type == "custom") | .skill_id]'
            delegateAgents: '[.multiagent.agents[]?.id] // []'
  - kind: session
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: '.title // .id'
          blueprint: '"claude_session"'
          properties:
            status: .status
            inputTokens: .usage.input_tokens
            outputTokens: .usage.output_tokens
            cacheReadInputTokens: .usage.cache_read_input_tokens
            activeSeconds: .stats.active_seconds
            durationSeconds: .stats.duration_seconds
            agentVersion: .agent.version
            githubRepositories: '[.resources[]? | select(.type == "github_repository") | .url]'
            metadata: .metadata
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at
          relations:
            agent: .agent.id
            environment: .environment_id
            memoryStores: '[.resources[]? | select(.type == "memory_store") | .memory_store_id]'
            vaults: .vault_ids

Mapping & examples per resource

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

{
  "identifier": "claude_agent",
  "title": "Claude Agent",
  "icon": "Claude",
  "schema": {
    "properties": {
      "description": {
        "type": "string",
        "title": "Description"
      },
      "model": {
        "type": "string",
        "title": "Model"
      },
      "system": {
        "type": "string",
        "title": "System prompt"
      },
      "version": {
        "type": "number",
        "title": "Version"
      },
      "metadata": {
        "type": "object",
        "title": "Metadata"
      },
      "mcpServers": {
        "type": "array",
        "title": "MCP servers",
        "items": {
          "type": "string"
        }
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Updated At"
      },
      "archivedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Archived At"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "skills": {
      "title": "Skills",
      "target": "claude_skill",
      "required": false,
      "many": true
    },
    "delegateAgents": {
      "title": "Delegate agents",
      "target": "claude_agent",
      "required": false,
      "many": true
    }
  }
}

resources:
  - kind: agent
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"claude_agent"'
          properties:
            description: .description
            model: .model.id
            system: .system
            version: .version
            metadata: .metadata
            mcpServers: '[.mcp_servers[]?.name] // []'
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at
          relations:
            skills: '[.skills[]? | select(.type == "custom") | .skill_id]'
            delegateAgents: '[.multiagent.agents[]?.id] // []'

{
  "id": "agt_01abc123def456",
  "name": "Code Review Agent",
  "description": "Reviews pull requests and suggests improvements.",
  "model": {
    "id": "claude-sonnet-4-5"
  },
  "system": "You are a senior software engineer. Review code changes for correctness, style, and security.",
  "version": 2,
  "metadata": {
    "team": "platform",
    "owner": "alice"
  },
  "mcp_servers": [
    { "name": "github", "url": "https://mcp.github.com" }
  ],
  "skills": [
    { "type": "custom", "skill_id": "skl_01review111" }
  ],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      { "id": "agt_01delegate222", "type": "agent", "version": 1 }
    ]
  },
  "created_at": "2026-01-10T08:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z",
  "archived_at": null
}

{
  "identifier": "claude_environment",
  "title": "Claude Environment",
  "icon": "Claude",
  "schema": {
    "properties": {
      "description": {
        "type": "string",
        "title": "Description"
      },
      "scope": {
        "type": "string",
        "title": "Scope",
        "enum": ["organization", "account"]
      },
      "environmentType": {
        "type": "string",
        "title": "Environment type",
        "enum": ["cloud", "self_hosted"]
      },
      "metadata": {
        "type": "object",
        "title": "Metadata"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Updated At"
      },
      "archivedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Archived At"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

resources:
  - kind: environment
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"claude_environment"'
          properties:
            description: .description
            scope: .scope
            environmentType: .config.type
            metadata: .metadata
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at

{
  "id": "env_01xyz789abc",
  "name": "Default Environment",
  "description": "Organization-wide default execution environment.",
  "scope": "organization",
  "config": {
    "type": "cloud"
  },
  "metadata": {
    "region": "us-east-1"
  },
  "created_at": "2026-01-05T10:00:00Z",
  "updated_at": "2026-05-20T09:30:00Z",
  "archived_at": null
}

{
  "identifier": "claude_session",
  "title": "Claude Session",
  "icon": "Claude",
  "schema": {
    "properties": {
      "status": {
        "type": "string",
        "title": "Status",
        "enum": ["rescheduling", "running", "idle", "terminated"],
        "enumColors": {
          "rescheduling": "yellow",
          "running": "blue",
          "idle": "green",
          "terminated": "red"
        }
      },
      "inputTokens": {
        "type": "number",
        "title": "Input tokens"
      },
      "outputTokens": {
        "type": "number",
        "title": "Output tokens"
      },
      "cacheReadInputTokens": {
        "type": "number",
        "title": "Cache read input tokens"
      },
      "activeSeconds": {
        "type": "number",
        "title": "Active seconds"
      },
      "durationSeconds": {
        "type": "number",
        "title": "Duration seconds"
      },
      "agentVersion": {
        "type": "number",
        "title": "Agent version"
      },
      "githubRepositories": {
        "type": "array",
        "title": "GitHub repositories",
        "items": {
          "type": "string"
        }
      },
      "metadata": {
        "type": "object",
        "title": "Metadata"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Updated At"
      },
      "archivedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Archived At"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "agent": {
      "title": "Agent",
      "target": "claude_agent",
      "required": false,
      "many": false
    },
    "environment": {
      "title": "Environment",
      "target": "claude_environment",
      "required": false,
      "many": false
    },
    "memoryStores": {
      "title": "Memory stores",
      "target": "claude_memory_store",
      "required": false,
      "many": true
    },
    "vaults": {
      "title": "Vaults",
      "target": "claude_vault",
      "required": false,
      "many": true
    }
  }
}

resources:
  - kind: session
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: '.title // .id'
          blueprint: '"claude_session"'
          properties:
            status: .status
            inputTokens: .usage.input_tokens
            outputTokens: .usage.output_tokens
            cacheReadInputTokens: .usage.cache_read_input_tokens
            activeSeconds: .stats.active_seconds
            durationSeconds: .stats.duration_seconds
            agentVersion: .agent.version
            githubRepositories: '[.resources[]? | select(.type == "github_repository") | .url]'
            metadata: .metadata
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at
          relations:
            agent: .agent.id
            environment: .environment_id
            memoryStores: '[.resources[]? | select(.type == "memory_store") | .memory_store_id]'
            vaults: .vault_ids

{
  "id": "ses_01pqr456stu",
  "title": "Review PR #142",
  "status": "idle",
  "agent": {
    "id": "agt_01abc123def456",
    "version": 2
  },
  "environment_id": "env_01xyz789abc",
  "vault_ids": ["vlt_01aaa111bbb"],
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/my-org/my-repo"
    },
    {
      "type": "memory_store",
      "memory_store_id": "mem_01ccc222ddd"
    }
  ],
  "usage": {
    "input_tokens": 4200,
    "output_tokens": 1800,
    "cache_read_input_tokens": 500
  },
  "stats": {
    "active_seconds": 47.3,
    "duration_seconds": 120.0
  },
  "metadata": {
    "pr_number": "142",
    "repo": "my-org/my-repo"
  },
  "created_at": "2026-06-15T14:00:00Z",
  "updated_at": "2026-06-15T14:05:30Z",
  "archived_at": null
}

{
  "identifier": "claude_vault",
  "title": "Claude Vault",
  "icon": "Claude",
  "schema": {
    "properties": {
      "metadata": {
        "type": "object",
        "title": "Metadata"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Updated At"
      },
      "archivedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Archived At"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

resources:
  - kind: vault
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .display_name
          blueprint: '"claude_vault"'
          properties:
            metadata: .metadata
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at

{
  "id": "vlt_01aaa111bbb",
  "display_name": "Port MCP",
  "metadata": {
    "purpose": "port-mcp-credentials"
  },
  "created_at": "2026-02-01T09:00:00Z",
  "updated_at": "2026-02-01T09:00:00Z",
  "archived_at": null
}

{
  "identifier": "claude_memory_store",
  "title": "Claude Memory Store",
  "icon": "Claude",
  "schema": {
    "properties": {
      "description": {
        "type": "string",
        "title": "Description"
      },
      "metadata": {
        "type": "object",
        "title": "Metadata"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Updated At"
      },
      "archivedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Archived At"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

resources:
  - kind: memory-store
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"claude_memory_store"'
          properties:
            description: .description
            metadata: .metadata
            createdAt: .created_at
            updatedAt: .updated_at
            archivedAt: .archived_at

{
  "id": "mem_01ccc222ddd",
  "name": "Engineering Context",
  "description": "Long-term memory for engineering best practices and team conventions.",
  "metadata": {
    "team": "platform"
  },
  "created_at": "2026-03-10T11:00:00Z",
  "updated_at": "2026-06-20T08:45:00Z",
  "archived_at": null
}

{
  "identifier": "claude_skill",
  "title": "Claude Skill",
  "icon": "Claude",
  "schema": {
    "properties": {
      "displayTitle": {
        "type": "string",
        "title": "Display title"
      },
      "source": {
        "type": "string",
        "title": "Source",
        "enum": ["custom", "anthropic"]
      },
      "latestVersion": {
        "type": "string",
        "title": "Latest version"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "title": "Updated At"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

resources:
  - kind: skill
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: '.display_title // .id'
          blueprint: '"claude_skill"'
          properties:
            displayTitle: .display_title
            source: .source
            latestVersion: .latest_version
            createdAt: .created_at
            updatedAt: .updated_at

{
  "id": "skl_01eee333fff",
  "display_title": "Port Catalog Reader",
  "source": "custom",
  "latest_version": "1.2.0",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-06-10T14:00:00Z"
}

Monitoring and sync status

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