Custom connectors

Connect a service that is not in the catalog with a Custom datasource. An Administrator's agent writes its connector module; the Administrator signs in or enters credentials, permits development runs, and approves Requests for regular use.

Create the datasource

Connect your agent to the Project as an Administrator. Agree on the service, the work it should do, and the authentication it needs. The agent checks the catalog and creates a Custom datasource for a service that is not listed. On Setup → Connect your agent, under Set your permissions, Full permissions includes datasource creation and is on by default for a new Project. If the Project uses narrower permissions, check Datasource creation through MCP in the individual permission cards.

The agent declares the service's OAuth resource and scopes for supported OAuth sign-in, or the credential names and fields the connector needs. Credential values do not belong in the conversation, connector source, or parameters. A public service can be declared as needing no credentials.

Sign in and allow the agent to build

Open the hosted credential page supplied for this datasource. Sign in for OAuth, or enter the requested credentials on that page and choose Mark ready if asked. OAuth uses the sign-in flow, not a pasted token. Tell the agent when you have finished so it can check the connection's status.

On the datasource's Setup step, beside its sign-in or credentials link, enable Let your AI agent build and test this connection. Only an Administrator can grant this permission. It allows the agent to publish connector code and try operations before Request approval. Ekaya runs that code but does not review it. This permission does not approve Requests; Requests already approved keep working if you turn it off.

Publish, try, and approve

1. The agent writes a Python connector module and its manifest, declaring operations, parameters, output, and the hosts it needs to reach. Credential declarations must match the datasource's declaration. Start with read operations: Custom modules that call an API directly support reads, not arbitrary writes.
2. The agent publishes the module to the ready Custom datasource. Its operations become Pending Requests for review.
3. With the build-and-test permission enabled, the agent tries a published operation in a development run, checks the returned rows or document and diagnostics, and fixes and republishes the module as needed. A development read reaches the connected service; it is not a mock. It does not approve a Request or establish that an approved run has succeeded.
4. The Administrator reviews the operation, parameters, output, and limits in Pending Requests, then approves the Requests needed for regular use. Grant narrowly to the intended Roles or Data Access Points. A Query reads; an Action changes something. Classify the operation by its effect, not its name.

When the connection uses credentials, development and approved runs call the service as that connection's single stored credential: the OAuth sign-in or entered service credential, not each caller's own account. Per-person access requires the operation to declare a parameter bound to the verified person, the connector to use it, and the upstream API to enforce that restriction. Binding a parameter alone does not isolate each person's records.

Publishing a changed operation requires approval again before callers can use it. Use the current approved contract when calling a Request or building a Hosted Application.

Execution and network limits

The Request Service stops a connector run at the deployment's execution ceiling: 60 seconds on Ekaya Cloud. A longer timeout in the module's manifest does not extend that ceiling. Keep pagination and individual calls within the run's time budget; a timeout is not a complete result.

On Ekaya Cloud, the connector can reach only the hosts its manifest declares for the operation. Top-level hosts apply to every operation; an operation can declare additional hosts. Declare bare hostnames, without a scheme, port, path, or wildcard. With no declared hosts, the sandbox network is closed, including for an OAuth connector.

The development run's answer reports its network mode and allowed hosts. Check them alongside the result. A local runner can report unrestricted access; that is not evidence that the Cloud host restriction was enforced. Keep the execution identifier and diagnostics when investigating a failure, and do not consume partial output from a failed run.