docs(mcp): explain conflicting destination streams in `create_connection_on_cloud` and point to `table_prefix`

Open Beginner friendly
  • Is something wrong?
#1,404 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
data-engineering, documentation

Research direction

Start by reading the create_connection_on_cloud docstring and the table_prefix field description, then trace how connection-conflicting-destination-stream errors are handled and where data.streams is available. Update the guidance to explain table name conflicts and how table_prefix separates them, including conflicting stream names and connection IDs; done when the tool docs and error guidance cover these steps.

Written by the indexing model from the issue text.

Description

Requested by AJ Steers (@aaronsteers), from a hosted Cloud MCP failure review (Datadog LLM Obs tool spans, Oct 4–16 2026).

Problem

This error is expected Cloud validation, not a bug. Cloud rejects a new connection when any of its streams would write to the same destination table (namespace + name) that another connection on that destination already writes to. The response is 400 error:connection-conflicting-destination-stream:

One or more streams in this connection write to a destination location that another connection already uses. Choose a different namespace or stream prefix for the conflicting streams.

The response's data.streams lists each conflicting stream and the connection IDs it conflicts with.

create_connection_on_cloud already passes the detail text through (since #1368). But the agent still doesn't have what it needs to fix the call:

  • data.streams is dropped, so the agent doesn't know which streams clash or which existing connection owns those tables;
  • the text says "namespace or stream prefix", but the tool only offers table_prefix (no namespace option), and the error doesn't name that parameter;
  • the tool docstring and the table_prefix description ("Optional table prefix to use when syncing to the destination.") don't mention this rule.

Evidence

  • Oct 14, one customer (rc.30): the agent was creating several connections from same-type sources into one destination. It hit this error twice, never retried with table_prefix, then tried schema-qualified stream names (also rejected), and in the end selected only the tables whose names didn't clash.
  • 4 occurrences in Oct 4–16, all from create_connection_on_cloud.

Proposed fix (guidance only)

  1. create_connection_on_cloud docstring: say that two connections into the same destination can't write to the same table name, and that table_prefix (for example <source>_) is the way to keep them apart.
  2. table_prefix field description: mention the same rule.
  3. On connection-conflicting-destination-stream, add guidance that names table_prefix and lists the conflicting stream names and connection IDs from data.streams (if this is too verbose, cap the list).

Written by Devin

Dominant language
Python
Stars
342
Forks
82
Avg merge
1d 7h
Merged PRs (30d)
74

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from airbytehq/PyAirbyte

All issues in airbytehq/PyAirbyte

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.