# Custom connectors

> Declare an operation with its inputs, outputs and credentials, and it becomes a process step, a workflow step, an agent tool and an audited event without writing any of those four

Source: https://aipril.dev/docs/platform/integrations/custom-connectors

## The generic path first

Most integrations do not need a connector family. The `http` connector calls any REST API with typed
inputs and outputs, passing through the same server-side request forgery guard as every other
administrator-supplied URL on the platform - so a service with an ordinary API is a configuration
step, not a build.

Use it for: a supplier API, an internal service, a partner endpoint, anything with a documented HTTP
contract.

## When to write a family

Write one when the target has a shape worth encoding once: a token refresh, pagination, rate limits,
an idempotency convention, several operations that share a client.

What you declare:

| Declaration | Effect |
|---|---|
| Operation manifest - inputs, outputs, failure modes | It appears as a process step and a workflow step, typed |
| Credential fields | Stored encrypted per organisation, resolved at call time, never in a definition |
| Risk classification | The [gate](https://aipril.dev/docs/harness/invocation.md) knows whether an agent may call it unattended |
| Access level | Whether non-administrators see it at all |

Declaring those four is the entire integration surface. Retry, compensation, payload encryption,
quotas and audit come from the runtime, not from your code.

## Reaching a service that speaks MCP

If the target already exposes an MCP server, there is a shorter path: install it as an
`mcp-proxy` skill. Configuration is stored encrypted, calls are forwarded over JSON-RPC, and the
endpoint is treated as untrusted input the same way any administrator-supplied URL is. See
[Skills](https://aipril.dev/docs/harness/skills.md).

## And an application can ship one

A connector configuration is an artifact of an [application](https://aipril.dev/docs/apps/under-the-hood.md), so an
integration travels with the app that needs it: versioned in its repository, installed by the
reconciler, and rolled back with it.