Choose the route to an outside system

An organization reaches outside systems through its connections: mail, accounting, ads, media generation, a database. An agent calls every connection inside run, under the organization's authority and its approval settings, and each call is recorded in the organization's run log. A connection is one of two kinds, and the rule for choosing is short. Use the built-in integration when it covers the operation. Use a custom connection for what the built-in integration lacks. Send money and bookkeeping writes through the built-in integration whenever the provider has one, and leave to a person what that integration deliberately leaves out.

Whose connections you use

Each organization has its own connections, and only members who may use them, with the Writer or Admin role, can list or call them. A Reader's agent, or an agent reading an organization it is not a member of, such as a public one, cannot. Work in the organization the task belongs to and use only its connections. If you work for several clients in separate organizations, never use one organization's connection for another's work. The listSources call of a namespace can return connections from every organization you belong to, so check which organization a source belongs to before you use it (Work across several organizations).

Use the organization's connection rather than a connector in your own client for the same system, so the call follows the organization's approval settings and is recorded where its work lives. If the organization's AGENTS.md says which connection serves a task, follow it. If the organization has no connection for the system, say so before you reach for another route, and let the person decide.

Two kinds of connection

Built-in integrations each have a namespace named after the provider, such as gmail, sevdesk or googleads. Oddlynew maintains their methods and their manual, and sets the consequence class of each write. Many writes take an operation id that you generate and keep a receipt, so calling again with the same id never acts twice. Some methods also check for requests the provider would accept without complaint. SevDesk, for example, accepts a booking with the wrong sign or amount, and sevdesk.bookVoucher refuses that booking before it is sent.

Custom connections come in two forms: an HTTP API that an admin connected from its OpenAPI description (the api namespace, APIs Integration), or a remote MCP server (the mcp namespace, MCP Servers Integration). They reach whatever the API or the server offers, but Oddlynew has not reviewed them. Arguments are checked against the schema the API or server publishes, and nothing more: nothing on the way knows the provider's pitfalls. A write's starting policy comes from its HTTP method or from the server's own labels, and each call is sent once and never retried.

Which one to use

Look before you choose. organizations.listConnections({ organizationId }) lists every connection of the organization with the namespace that calls it, its health, its access level and its confirmation setting for each consequence class. To see a namespace's methods, ask guide with explain set to the namespace name. One provider can appear twice, once as a built-in integration and once as a custom connection.
Use the built-in integration when it has a method for the operation and the organization has a usable connection for it: active, not paused, and at an access level that allows the call. Some built-in integrations also offer a guarded general request for endpoints that have no method of their own, such as sevdesk.request. That still counts as the built-in route.
Use a custom connection when the built-in integration lacks the operation, or when the system has no built-in integration at all. Money and bookkeeping writes follow the stricter rule below. Tell the person, or note in the record of the work, which operation sent you there, so the missing method stays visible.
If a built-in integration covers the operation but cannot serve it now, because the organization has not connected it, the connection needs a new sign-in or its access level does not allow the call, a read may go through a custom connection the organization already has to the same provider in the meantime. A write waits: do not route it through a custom connection instead. For a connection that needs attention, give an admin the pageUrl that listConnections returns for it. For a provider the organization has not connected, point an admin to the organization's Integrations page.

Money and bookkeeping writes

Writes that move money or change the books, such as creating, booking or deleting a voucher, creating or cancelling an invoice, or changing an ad budget, go only through the built-in integration whenever the provider has one. Its functions check what the provider does not, and SevDesk's keep a receipt, so an unclear outcome is checked rather than repeated. Never send such a write through a custom connection to the same provider's API or MCP server, even when that connection would allow it.

What a built-in integration deliberately leaves out stays a step for a person in the provider's own app. The SevDesk integration, for example, creates and edits invoices only as drafts. Issuing or sending a document, booking an invoice's payment and finalizing the books stay in SevDesk, because over its API some of those steps lock a document for good. Its general request refuses them too (The request escape hatch). Do not complete such a step through a custom connection. Prepare the work and tell the person what is ready for them.

When the provider has no built-in integration, for example a payment provider without one, a custom connection is the only route. Keep its money writes waiting for a person. An API operation other than GET or HEAD waits for confirmation by default. An MCP tool that its server labels as not destructive, however, starts as a medium write, and medium writes run without confirmation by default (Integration approvals). mcp.listTools and api.listOperations show the consequence class of each tool or operation, and listConnections shows whether that class waits for confirmation on the connection. If a money tool would run on its own, ask an admin to make that class wait for confirmation on the connection, or to block the tool, before you call it.

For the person who connects

Connect an API to your organization and Connect an MCP server to your organization describe the admin steps for custom connections.