Data Connectors

Build Data Connectors with AI Agents

Point a coding agent at the extension docs, give it a starter prompt, and know which steps still need you.
Preview
Extensions are in preview and can change in breaking ways between releases. Use them in non-production environments only. See Stability. Written for Monospace 1.0.0, @monospace/cli 0.2 and @monospace/extension-kit 0.3.

Overview

A coding agent can build an extension end to end. Point it at these docs instead of its memory, and stay in the loop for the steps it can't check. Each entry type has its own workflow.

Data connectors are the only entry type today, so this page covers building a data connector extension. It exposes an external data source (the API, service, or database the connector reads and writes) as collections in a Monospace workspace. The agent probes the external data source, writes the connector, and climbs the test ladder.

This page covers what to give the agent, a prompt to start from, the rules to hold it to, and what an agent can't verify alone.

Give the Agent the Docs

Every docs page has a markdown version, and the site publishes two index files for language models.

URLContents
https://docs.monospace.io/llms.txtEvery page's title, description, and markdown URL
https://docs.monospace.io/llms-full.txtThe full text of every page in one file
https://docs.monospace.io/raw/en/<page path>.mdOne page as markdown (e.g., https://docs.monospace.io/raw/en/developer/extensions/data-connectors/runtime.md)
https://docs.monospace.io/en/<page path>One page as HTML (e.g., https://docs.monospace.io/en/developer/extensions/data-connectors/runtime)

Give the agent the markdown URLs of the extension pages rather than llms-full.txt. The full file covers the whole platform, and most of it is unrelated to extensions.

Read these pages in this order. The agent needs the runtime model and the limitations before it writes code:

PageWhy the agent needs it
How Data Connectors RunThe sandbox: one file, no Node APIs, configuration instead of environment variables
Data ConnectorsLive queries, the operations contract, and the Fit Check
LimitationsWhat a connector can't do, and the workaround for each
Build a Stripe Data ConnectorThe build, step by step
Map an External Data SourceProbing, filters, paging, keys, and writes
Handle ErrorsWhich error class to throw for each failure of the external data source
Test a Data ConnectorThe test ladder
Data Connector API, Operations and Operators, Errors, Network Permissions, CLIExact shapes, rules, and codes to check against
Data Connector Module, Protocol Types, Schema HelpersThe declaration of every export of @monospace/extension-kit

Start with a Prompt

Copy this prompt, fill in the angle-bracket parts, and give it to your agent in the directory where the connector project goes. It points the agent at the docs, sets the safety defaults, and makes it stop at the checkpoints where you decide.

The checkpoints matter more than the rules. The first one catches an external data source that doesn't fit before any code exists, and the second keeps network approval with you.

Rules for the Agent

Hold the agent to these rules. Each links to the page that owns the detail.

RuleWhat goes wrong without it
Run the Fit Check first, and ask when a limitation blocks the request. See Fit CheckThe agent builds around a required filter or an unwritable reference, and the user finds out in Studio
Probe the live external data source, and declare only what a request you ran answers. See Map an External Data SourceDeclarations based on vendor docs fail at runtime. The Art Institute of Chicago API documents 10,000 search results, and refuses past 1,000
Put fixed hosts in the manifest. Use preflight only for hosts derived from configuration. Validate the configuration in setup. preflight may throw InvalidConfiguration for the part it reads. See Network PermissionsA preflight that declares fixed hosts hides the grant from the manifest
Write web-platform code only. See How Data Connectors Run. Need a Node.js-compatible API? Let us knownode:* imports fail the build, and Deno.env or filesystem calls throw NotCapable at runtime
Run the linter, tsc and unit tests; the build doesn't typecheck. See Lint, Typecheck, and Run Unit TestsA green build ships a type error, or an error mapping that only a timeout or a 429 would exercise
Create a data source before writing query code, and check every relation in the workspace's OpenAPI document. See Test a Data ConnectorEngine checks declarations when a data source is created or reintrospected, not at build time or on the raw /sources/data/introspect endpoint. A reload doesn't refresh a data source's stored declarations either; reintrospect after changing them. It narrows a relation direction it can't serve with only a log warning
Serve or refuse: never scan, never truncate. Refuse with QueryRejected (or a plain Error for what you didn't declare) as early as the connector can tell, fill the whole limit unless the matching items run out, and break sort ties with the stable ID. See Handle ErrorsA short page reads as "no more items", and a scan burns the external data source's rate limit
Re-check every returned item against the filter when the external data source's match is broader than the declared operator (e.g., case-insensitive or substring), and keep fetching when the re-check drops items, so the page still fills its limit. See Map an External Data SourceCallers get items that don't match their filter, or a short page that reads as the end of the data
Answer { record: null } for a keyed miss, and check the guard before any write. See Keyed OperationsA guard miss still writes, or answers an item the guard excludes. A plain Error or a records answer fails the caller's request with 500 instead of 404
Map errors in one client, use InvalidConfiguration only for configuration and AccessDenied only for an account the external data source refuses (rejected credentials, a missing scope, or a resource it can't reach). Give every request a deadline, and wrap a fetch rejection with { cause }, so a permission denial stays one. See Handle ErrorsCallers are told their configuration is invalid when the external data source is down, see an internal error, or wait on a request that never answers
Assert what goes on the wire, and make every check fail once. See Test a Data ConnectorChecks pass against a fixture that ignores the parameter being tested
Report honestly. List skipped rungs, and exit non-zero from a run that skipped checks"All tests pass" means only the rungs that ran

Know What the Agent Can't Verify Alone

Some steps need a person, credentials, or an instance (a Monospace deployment) the agent can't reach. Plan for these before you start, and ask the agent to list them in its final report.

StepWhy the agent needs you
Approving network permissionsDeciding which hosts a data source may reach is your call. Review meta.permissions before the agent resends them. The grant must contain exactly the required hosts, ports and wildcards; reasons aren't compared
CredentialsThe agent needs a test-mode or sandbox credential from you. Never give it production credentials
Installing into your instanceThe agent needs write access to the instance's install location, and a restart or automatic reloading. See Install and Manage Extensions
Behavior that needs live trafficReal rate limits and paging depth show up only against the real external data source, often only under load. The agent can test its 429 and 5xx mapping alone with a stand-in that injects them
StudioBrowsing, filtering, and editing in Studio, and judging whether each error message helps a user. No example automates it. See Try It in Studio

See Also

MonospaceThe governed API layer for every app, person, and agent.

Copyright © 2026 Monospace Inc.