//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: 47 managed connectors.
• Governed tools: 464 tools.
• Side-effect levels: L0=10, L1=296, L2=14, L3=99, L4=45.
• High-impact tools requiring approval by default: 45.
• 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.

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.

BigQuery (bigquery)

Governed BigQuery connector for datasets, tables, jobs, bounded query execution, dry-run estimates, and approval-gated warehouse operations.

Auth requirements:

Scope/data-class map:

Tool summary:

Tool details:

bigquery.list_projects

List BigQuery projects.

Input contract:

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

bigquery.list_datasets

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

bigquery.list_tables

List tables in a dataset.

Input contract:

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

bigquery.describe_table

Read BigQuery table metadata.

Input contract:

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

bigquery.get_table_schema

Read normalized BigQuery table schema fields.

Input contract:

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

bigquery.dry_run_query

Validate read-only SQL and return an estimated execution plan.

Input contract:

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

bigquery.execute_query

Execute bounded read-only BigQuery SQL.

Input contract:

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

bigquery.list_jobs

List recent BigQuery jobs.

Input contract:

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

bigquery.get_job

Read a BigQuery job by id.

Input contract:

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

bigquery.cancel_job

Cancel a BigQuery job after approval.

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.

Box (box)

Governed Box connector for enterprise content search, metadata, comments, collaborations, and safe sharing actions.

Auth requirements:

Scope/data-class map:

Tool summary:

Tool details:

box.search_files

Search Box files and folders.

Input contract:

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

box.list_folder_items

List Box folder items.

Input contract:

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

box.get_file_metadata

Read Box file metadata.

Input contract:

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

box.get_folder_metadata

Read Box folder metadata.

Input contract:

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

box.get_file_text

Read bounded text content from a Box file fixture or representation.

Input contract:

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

box.list_comments

List comments on Box files.

Input contract:

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

box.list_collaborations

List Box collaborations.

Input contract:

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

box.create_shared_link

Plan or create a Box shared link.

Input contract:

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

box.create_folder

Plan or create a Box folder.

Input contract:

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

box.upload_file_draft

Prepare a bounded Box upload plan.

Input contract:

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

Calendly (calendly)

Governed Calendly connector for event types, scheduled events, invitees, availability, users, organization membership, and safe scheduling changes.

Auth requirements:

Scope/data-class map:

Tool summary: