Skip to content

Solution Design Playbook

Connectors: two jobs

Connectors: two jobs

A connector links raia to a system you already run. It can do two very different jobs, and a good design says which one it's doing.

Import

Copies relatively stable content, such as articles, documents or pages, into a Command knowledge folder. From there it's converted, scanned and trained into an agent like any other knowledge.

Agent access

Gives an agent live tools in the system, such as search, look up, get details, create a case, create a task or update a field, so it can read and act at the moment it's needed.

Import

Use import for approved content that doesn't change by the hour. Depending on the source, you can import once or refresh on a schedule. Searching a well-prepared local copy usually gives richer answers than asking a remote system's search for each question.

Content can come from many places:

  • Business systems such as Salesforce, Zendesk, Zoho, GitBook, Google Drive and SharePoint
  • Websites, using a basic scrape for simple pages, or a browser-based crawl for sites that build their content with JavaScript
  • HTTP and SOAP endpoints
  • File drops and video, which produce transcripts and descriptions

Learn more: Connectors and the Connectors directory.

Agent access

Agent access exposes selected tools to an agent over MCP. Many connectors offer this through a bridge in Command, which handles sign-in and credentials and gives the agent an MCP endpoint to add under its integrations.

Three separate settings decide what an agent can actually do. Scope all three on purpose:

  1. The permissions of the account the connector signs in with.
  2. The tools the bridge exposes.
  3. The tools you select on the agent.

Instructions are not a fourth layer of protection. If an agent shouldn't create records, don't give it the create tool.

Setting up a connector can take care, especially where enterprise identity permissions are involved. Once it's done, the same connection can serve several agents, each with its own bridge and its own selection of tools. For SharePoint, prefer access to specific sites over tenant-wide permissions.

Learn more: MCP Servers, MCP integrations and SharePoint site-specific setup.

Using both

Many good designs use the same system both ways. A support agent might:

  • Import help articles, for rich, well-sourced answers.
  • Fetch one article live, only when being current really matters.
  • Create a CRM case through a single scoped write tool, when the customer asks, when the conversation ends, or when it's escalated.

Decide whether each action happens inside the conversation, by the agent, or afterwards, by a Loop. They're different designs with different trade-offs. See Loops and outbound.

Shaping APIs for agents

For telemetry, enterprise databases and other structured data, it often pays to build a dedicated MCP layer on top of an existing API. Design it for the questions people actually ask. If a common question takes four API calls, a purpose-built read-only endpoint can return the answer in one, which is faster, cheaper and leaves less room for error. Keep exact arithmetic in code, not in the model.

Describing a connector in a blueprint

For each connector, write down:

  • The system and who owns the sign-in.
  • Whether it's used for import, agent access, or both.
  • What it imports, and how often it refreshes.
  • Which tools the agent gets, and which of them can change data.
  • How freshness is handled for anything that changes.