> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polycore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> The supported integration surfaces and how Polycore connects data platforms, interfaces, and customer code.

An integration connects a project capability to the Polycore catalog. Customer
hosted runners keep private-network credentials in your infrastructure. Shared
SaaS direct integrations use a separate private Polycore executor with encrypted
provider grants and never expose those grants to callers or the public control
plane.

During early access, every integration is planned and implemented with the
Polycore team. The pages in this section explain the architecture, IAM shape,
configuration, and validation you can expect.

<Info>
  This is not a self-serve connector directory. If your system is not listed,
  [request early access](https://www.polycore.ai/early-access) and describe the
  workflow. We add integrations around real customer requirements.
</Info>

## Direct SaaS integrations

<Columns cols={2}>
  <Card title="Notion" icon="book-open">
    A read-only, project-wide shared internal connection for company knowledge.
    Owners and admins install the connection; Notion page sharing remains the
    provider-side resource boundary.
  </Card>

  <Card title="Shared team authority" icon="users-round">
    Direct integrations represent team resources rather than personal user
    accounts. Environment switching does not retarget project-wide connections.
  </Card>
</Columns>

Direct integrations are intentionally narrow. They use typed provider operations,
fixed hosts, bounded requests and results, an isolated executor, and explicit MCP
service grants. Use a runner for private networks, production databases, custom
code, broad credentials, or customer-side credential custody.

## Data platforms

<Columns cols={3}>
  <Card title="Postgres" icon="database" href="/integrations/postgres" cta="View Postgres integration">
    Read-only schema discovery, query planning, and bounded SQL through a
    customer-hosted runner. Works with standard Postgres, including hosted
    services such as Supabase.
  </Card>

  <Card title="Firestore" icon="flame" href="/integrations/firestore" cta="View Firestore integration">
    Document and collection-group reads, server-side aggregations, live shape
    inference, and optional Typesync grounding through GCP IAM.
  </Card>

  <Card title="PostHog" icon="chart-no-axes-combined" href="/integrations/posthog" cta="View PostHog integration">
    Bounded HogQL, taxonomy discovery, behavioral segmentation, enrichment, and
    activity context for composition with live operational data.
  </Card>
</Columns>

Built-in data queries are read-only. Actions that change state and multi-system
workflows are represented as customer actions with explicit schemas, hazards,
and secret needs.

## Interfaces

<Columns cols={2}>
  <Card title="Slack" icon="message-square" href="/integrations/slack">
    A conversational agent for everyday requests, plus human approval cards for
    pending writes.
  </Card>

  <Card title="MCP" icon="cable" href="/integrations/mcp">
    Expose the same connected catalog to AI agents and development tools through
    a control-plane MCP endpoint.
  </Card>
</Columns>

Admin dashboards are another interface to the same catalog. They are described
under [Admin dashboards](/concepts/dashboards) because they compose connected
capabilities rather than add another downstream credential.

## Anatomy of an integration

```mermaid theme={"system"}
flowchart LR
  Scope["Workflow and authority"]
  Package["Your runner"]
  Deploy["Runner deployment"]
  Catalog["Governed catalog"]
  Doors["Slack, MCP, dashboards"]

  Scope --> Package --> Deploy --> Catalog --> Doors
```

<Columns cols={2}>
  <Card title="1. Capability surface" icon="list-tree">
    Enabled built-in query families plus named actions. This is the complete
    catalog the runner advertises.
  </Card>

  <Card title="2. Domain context" icon="file-text">
    A concise project document that explains terms, identifiers, and safe
    interpretation rules to the agent.
  </Card>

  <Card title="3. Runtime identity" icon="badge-check">
    One runner registration for one Polycore project and environment, plus the
    cloud or network identity used inside that environment.
  </Card>

  <Card title="4. Deployment path" icon="git-pull-request-arrow">
    A repository, container image, infrastructure definition, and secret
    injection path owned by your team.
  </Card>
</Columns>

## Read and write paths

<Tabs>
  <Tab title="Broad read">
    Enable a built-in query family and bind a read-only identity. The agent can
    inspect the schema and compose bounded reads without a custom action for
    every question.
  </Tab>

  <Tab title="Named operation">
    Add a typed action to your runner. The action can combine business rules or
    call an internal API. Its hazard is one input your access policy uses to
    decide whether an approval record is required before dispatch.
  </Tab>

  <Tab title="Human workflow">
    Compose connected capabilities into a dashboard page. The page receives no
    new execution authority and calls the same catalog through `polycore.run`.
  </Tab>
</Tabs>

## Integration principles

<AccordionGroup>
  <Accordion title="Start from a workflow" icon="route">
    We choose a valuable production read and a representative governed change
    before choosing implementation details.
  </Accordion>

  <Accordion title="Keep credentials at the right boundary" icon="lock-keyhole">
    Workload identity, database URLs, and private API keys are resolved by the
    runner in your infrastructure. Shared SaaS grants are encrypted and used
    only inside the isolated hosted executor, not stored in public control-plane
    metadata.
  </Accordion>

  <Accordion title="Use native least privilege" icon="shield-check">
    IAM, SQL grants, restricted API keys, and network controls remain the first
    enforcement layer.
  </Accordion>

  <Accordion title="Review standing authority as code" icon="git-branch">
    Query families, actions, schemas, and project context live in your runner.
    Changes reach a deployed instance through your deployment.
  </Accordion>

  <Accordion title="Prove failure paths" icon="triangle-alert">
    A successful demo is not enough. We validate missing permissions, denied
    writes, unavailable runners, bounded results, and audit records.
  </Accordion>
</AccordionGroup>

## Adding another platform

A new platform usually needs some combination of:

1. A least-privilege identity and deployment binding.
2. A constrained generic read surface, when the platform has a broad query
   model.
3. Named actions for stable operations and writes.
4. Tool descriptions and project context that let agents choose the surface
   correctly.
5. Integration tests and an operational deployment path.

<Check>
  Have a platform or internal API you want to connect? Include it in your
  [early-access request](https://www.polycore.ai/early-access). We will assess
  it against the workflow and trust model with you.
</Check>