//DOCS Connectors

Managed SaaS Connectors

Punk's managed connectors are installable, first-party MCP servers for common SaaS systems. This page is generated from the manifest-backed catalog in apps/connectors/src/connectors/*/manifest.json and reflects what GET /api/v1/connectors/catalog exposes.

Connector vs. Tool

A connector is one installable integration, such as Slack or GitHub. A governed tool is one action exposed by that connector, such as slack.post_message or github.search_issues. Each tool carries governance metadata: side-effect level, action label, cache posture, replay mode, shadow behavior, idempotency posture, redaction metadata, and whether approval is required by default.

Availability Summary

• Manifest-backed catalog: 51 managed connectors.
• Governed tools: 517 tools.
• Side-effect levels: L0=11, L1=331, L2=14, L3=104, L4=57.
• High-impact tools requiring approval by default: 57.
• Registry-only IDs not exposed by the catalog yet: webhook, observability. They appear in the static connector registry but have no manifest directory, so they are not installable through the managed connector catalog today.

Recent Additions

The latest connector tranche expands Punk's governed coverage across engineering delivery, cloud operations, edge infrastructure, and infrastructure-as-code.

How Humans Should Use This Page

1. Pick the connector from the catalog table and confirm its categories, data classes, auth mode, and vendor docs.
2. Review the connector's auth requirements and least-privilege scopes before installing it.
3. Inspect each tool's side-effect level, approval default, idempotency requirement, replay mode, and shadow behavior before enabling writes.
4. Use fixture selfchecks and dry-run write calls before turning on live writes for a tenant.

How Agents Should Use This Page

1. Prefer L0/L1 read tools for context gathering and respect cache scope. tenant cache scope is shared tenant metadata; subject scope is user or subject-specific context.
2. Treat L2/L3/L4 tools as side-effecting. Keep dryRun true unless the user explicitly authorized execution and policy permits it.
3. For tools with idempotency support, always provide a stable idempotencyKey before execution.
4. For L4 tools, provide approval metadata and expect replay/shadow suppression. Never infer approval from conversational context alone.
5. Do not request raw body/transcript/content expansions unless required for the task and allowed by policy.
6. Use the /api/v1/connectors/catalog endpoint or manifest files as the machine-readable source of truth when building tool selectors.

Governance Semantics

Catalog

Runtime And Installation

Managed connector install uses the existing MCP runtime rather than a separate execution path. Installing a connector creates an encrypted credential, registers a stdio MCP server, injects field-qualified secret refs such as cred:<id>#access_token, and starts apps/connectors/src/index.ts <connector-id> in live mode. Fixture mode exists for deterministic demos and tests and must be explicitly selected. Missing live credentials fail closed instead of returning fixture data.

Install request shape:

{
  "connectorId": "slack",
  "name": "Slack managed connector",
  "secret": {
    "accessToken": "xoxb-..."
  }
}

You can provide credentialId instead of secret to reuse a stored credential for the same connector provider. Install rejects attempts to override Punk-managed live-mode metadata.

Complete Connector Reference

Airtable (airtable)

Airtable connector for bases, tables, records, comments, and governed batch record updates.

Auth requirements:

Scope/data-class map:

Tool summary:

Tool details:

airtable.list_bases

List Airtable bases visible to the credential.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

airtable.list_tables

List tables and fields in an Airtable base.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

airtable.list_records

List records from an Airtable table with optional view, fields, and text filtering.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

airtable.get_record

Fetch one Airtable record by id.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

airtable.list_comments

List Airtable record comments.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

airtable.create_record

Create one Airtable record. Dry-run is the default.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

airtable.update_record

Update one Airtable record. Dry-run is the default.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

airtable.batch_update_records

Update multiple Airtable records. Live execution requires explicit approval and idempotency.

Input contract:

Agent usage: High-impact action. Execution requires approval metadata, idempotency, explicit live-write enablement, and must never be run during replay or shadow.

airtable.comment_record

Add a comment to an Airtable record. Dry-run is the default.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

airtable.delete_record

Delete one Airtable record. Live execution requires explicit approval and idempotency.

Input contract:

Agent usage: High-impact action. Execution requires approval metadata, idempotency, explicit live-write enablement, and must never be run during replay or shadow.

Asana (asana)

Governed Asana connector for project, task, comment, user, and attachment workflows with safe write planning.

Auth requirements:

Scope/data-class map:

Tool summary:

Tool details:

asana.search_tasks

Search Asana tasks with bounded pagination.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

asana.get_task

Read a single Asana task by gid.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

asana.list_projects

List visible Asana projects.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

asana.get_project

Read an Asana project by gid.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

asana.list_project_tasks

List tasks in a project.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

asana.list_users

List Asana workspace users.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

asana.list_attachments

List attachments on a task.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

asana.list_comments

List comment stories on an Asana task.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

asana.add_comment

Plan or create an Asana task comment.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

asana.attach_file

Plan or attach a file reference to an Asana task. Live execution requires approval and idempotency.

Input contract:

Agent usage: High-impact action. Execution requires approval metadata, idempotency, explicit live-write enablement, and must never be run during replay or shadow.

asana.create_task

Plan or create an Asana task.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

asana.update_task

Plan or update task fields.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

Atlassian Jira and Confluence (atlassian)

Managed Atlassian Cloud connector for governed Jira issue operations and Confluence knowledge workflows.

Auth requirements:

Scope/data-class map:

Tool summary:

Tool details:

atlassian.jira_search_issues

Search Jira Cloud issues with JQL using the REST v3 enhanced JQL search endpoint.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

atlassian.jira_get_issue

Get a Jira Cloud issue by id or key with bounded normalized fields and optional raw payload.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

atlassian.jira_create_issue

Create a Jira Cloud issue. Description text is converted to Atlassian Document Format; writes default to dry-run.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

atlassian.jira_comment_issue

Add a Jira Cloud issue comment using Atlassian Document Format. Writes default to dry-run.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

atlassian.jira_update_issue

Update allowlisted Jira Cloud issue fields. Arbitrary transition and workflow operations are intentionally out of scope.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

atlassian.confluence_search

Search Confluence Cloud content with CQL through the official REST search endpoint.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

atlassian.confluence_get_page

Get a Confluence Cloud page by id with selected body representation and optional footer comments.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

atlassian.confluence_create_page

Create a Confluence Cloud page with storage or Atlassian document body. Writes default to dry-run.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

atlassian.confluence_comment_page

Create a Confluence Cloud footer comment on a page. Writes default to dry-run.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

AWS Operations (aws-ops)

Governed AWS operations connector for CloudWatch, Cost Explorer, resource inventory, IAM context, dry-run changes, and approval-gated remediation.

Auth requirements:

Scope/data-class map:

Tool summary:

Tool details:

aws.search_resources

Search AWS resources from inventory.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.get_resource

Read one AWS resource inventory record.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.query_cloudwatch_metrics

Query bounded CloudWatch metrics.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.search_cloudwatch_logs

Search CloudWatch logs with bounded time and result windows.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.list_alarms

List CloudWatch alarms.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.get_alarm

Read one CloudWatch alarm.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.query_costs

Read AWS Cost Explorer summaries.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.list_iam_principals

List bounded IAM principals.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.get_iam_policy

Read one IAM policy summary.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

aws.plan_alarm_update

Plan a CloudWatch alarm change without applying it.

Input contract:

Agent usage: Prefer dry-run first. Treat output as a draft or reversible plan until a human or policy confirms execution.

aws.apply_tags

Apply AWS resource tags when live writes are enabled.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

aws.remediate_resource

Run an approval-gated remediation action against an AWS resource.

Input contract:

Agent usage: High-impact action. Execution requires approval metadata, idempotency, explicit live-write enablement, and must never be run during replay or shadow.

Azure DevOps (azure-devops)

Governed Azure DevOps connector for projects, work items, Git repositories, pull requests, build logs, pipeline runs, and wiki updates.

Auth requirements:

Scope/data-class map:

Tool summary:

Tool details:

azuredevops.list_projects

List Azure DevOps team projects visible to the authenticated organization credential.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azuredevops.search_work_items

Search Azure DevOps work item fixtures or execute a bounded WIQL query in live mode.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azuredevops.get_work_item

Read one Azure DevOps work item by id with normalized fields and comments.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azuredevops.create_work_item

Plan or create an Azure DevOps work item. Live writes require explicit enablement and idempotency.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

azuredevops.update_work_item

Plan or update allowlisted Azure DevOps work item fields. Writes default to dry-run.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

azuredevops.list_repositories

List Azure DevOps Git repositories visible to the organization credential.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azuredevops.list_pull_requests

List pull requests for a repository using Azure DevOps Git REST APIs.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azuredevops.get_pull_request

Read one Azure DevOps pull request by repository and pull request id.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azuredevops.comment_pull_request

Plan or create an Azure DevOps pull request thread comment. Writes default to dry-run.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

azuredevops.list_builds

List Azure DevOps builds for a project with bounded filters.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azuredevops.get_build_logs

Read Azure DevOps build log metadata and fixture excerpts for one build.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azuredevops.queue_pipeline_run

Queue an Azure DevOps pipeline run. This level 4 write requires approval, idempotency, and explicit live-write enablement.

Input contract:

Agent usage: High-impact action. Execution requires approval metadata, idempotency, explicit live-write enablement, and must never be run during replay or shadow.

azuredevops.update_wiki_page

Plan or update an Azure DevOps wiki page through the Wiki Pages REST API. Writes default to dry-run.

Input contract:

Agent usage: Customer-visible or business-system write. Keep dryRun true for planning, provide idempotencyKey for execution, and expect replay/shadow suppression.

Azure Operations (azure-ops)

Governed Microsoft Azure operations connector for Resource Manager inventory, deployments, Monitor metrics, activity logs, Cost Management, dry-run operational plans, tag updates, App Service scaling, and approval-gated RBAC changes.

Auth requirements:

Scope/data-class map:

Tool summary:

Tool details:

azure.list_subscriptions

List Azure subscriptions visible to the supplied Azure Resource Manager token.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azure.list_resource_groups

List resource groups within one Azure subscription.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azure.search_resources

Search Azure resources through Resource Graph with a bounded query and result window.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azure.get_resource

Read one Azure Resource Manager resource by full resource ID.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azure.list_deployments

List ARM deployments for a resource group.

Input contract:

Agent usage: Use as context-gathering before model reasoning. Respect cache scope and request explicit sensitive expansions only when needed.

azure.get_deployment

Read one ARM deployment in a resource group.