Skip to main content
Glama
RawTree MCP Server

RawTree MCP Server

Official
by rawtreedb

Create Connector

create-connector

Creates an active Kafka or NATS JetStream connector that routes source topics or streams to RawTree destination tables, starting consumption after the connector is applied.

Instructions

Purpose: Create an active Kafka or NATS JetStream connector with one or more destinations. Settings and all destination fields must match the selected type.

Behavior: Consumption starts after the runtime applies the connector. Kafka destinations use independent consumer groups; omit group_id to generate one. NATS destinations require nats_stream and nats_consumer naming an existing durable pull consumer with explicit acknowledgements. RawTree does not create streams or consumers. Destination tables can be created automatically when their first events arrive.

Auth: Requires organization-admin access.

Safety: Confirm the exact organization, cluster, connector name, broker addresses, source topics or streams, consumer groups or durable consumers, and destination tables before calling. Treat SASL credentials, NATS passwords, tokens, and NKey seeds as secrets and never repeat them in confirmation text or logs.

Reliability: Creation is not idempotent. If the response is ambiguous, call list-connectors and reconcile by name before retrying.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>",
      "type": "<type>",
      "destinations": "<destinations>",
      "settings": "<settings>"
    },
    "name": "create-connector"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYes
typeYes
clusterNoRawTree cluster to use for this operation.
settingsYesSettings must match type: bootstrap_servers for kafka; servers and optional auth for nats.
destinationsYes
organizationNoRawTree organization containing the target cluster.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changedv0.4.9
    • removedInput schema / properties / destinations / items / additionalProperties
      Removed value: -false
    • addedInput schema / properties / destinations / items / anyOf
      Added value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "database": {
      +        "description": "Destination RawTree database.",
      +        "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      +        "type": "string"
      +      },
      +      "group_id": {
      +        "description": "Kafka consumer group. Omit to let RawTree generate an independent group for this destination.",
      +        "maxLength": 255,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "table": {
      +        "description": "Destination RawTree table.",
      +        "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      +        "type": "string"
      +      },
      +      "topics": {
      +        "description": "Kafka topics consumed by this destination.",
      +        "items": {
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "maxItems": 100,
      +        "minItems": 1,
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "topics",
      +      "database",
      +      "table"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "database": {
      +        "description": "RawTree database or table identifier.",
      +        "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      +        "type": "string"
      +      },
      +      "nats_consumer": {
      +        "description": "Existing durable pull consumer with explicit acknowledgements.",
      +        "maxLength": 255,
      +        "minLength": 1,
      +        "pattern": "^[^\\s.*>/\\\\]+$",
      +        "type": "string"
      +      },
      +      "nats_stream": {
      +        "description": "Existing JetStream stream name.",
      +        "maxLength": 255,
      +        "minLength": 1,
      +        "pattern": "^[^\\s.*>/\\\\]+$",
      +        "type": "string"
      +      },
      +      "table": {
      +        "description": "RawTree database or table identifier.",
      +        "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "nats_stream",
      +      "nats_consumer",
      +      "database",
      +      "table"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / destinations / items / properties
      Removed value: -{
      -  "database": {
      -    "description": "Destination RawTree database.",
      -    "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      -    "type": "string"
      -  },
      -  "group_id": {
      -    "description": "Kafka consumer group. Omit to let RawTree generate an independent group for this destination.",
      -    "maxLength": 255,
      -    "minLength": 1,
      -    "type": "string"
      -  },
      -  "table": {
      -    "description": "Destination RawTree table.",
      -    "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      -    "type": "string"
      -  },
      -  "topics": {
      -    "description": "Kafka topics consumed by this destination.",
      -    "items": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "maxItems": 100,
      -    "minItems": 1,
      -    "type": "array"
      -  }
      -}
    • removedInput schema / properties / destinations / items / required
      Removed value: -[
      -  "topics",
      -  "database",
      -  "table"
      -]
    • removedInput schema / properties / destinations / items / type
      Removed value: -"object"
    • removedInput schema / properties / settings / additionalProperties
      Removed value: -false
    • addedInput schema / properties / settings / anyOf
      Added value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "auto_offset_reset": {
      +        "description": "Offset policy when the consumer group has no committed offset. Defaults to largest.",
      +        "enum": [
      +          "largest",
      +          "smallest"
      +        ],
      +        "type": "string"
      +      },
      +      "batch": {
      +        "additionalProperties": false,
      +        "description": "Optional HTTP delivery batch settings.",
      +        "properties": {
      +          "max_events": {
      +            "maximum": 100000,
      +            "minimum": 1,
      +            "type": "integer"
      +          },
      +          "timeout_secs": {
      +            "exclusiveMinimum": 0,
      +            "maximum": 60,
      +            "type": "number"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "bootstrap_servers": {
      +        "description": "Kafka bootstrap server addresses.",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "sasl": {
      +        "additionalProperties": false,
      +        "description": "SASL credentials. Omit sasl for an unauthenticated Kafka connection.",
      +        "properties": {
      +          "enabled": {
      +            "const": true,
      +            "type": "boolean"
      +          },
      +          "mechanism": {
      +            "enum": [
      +              "PLAIN",
      +              "SCRAM-SHA-256",
      +              "SCRAM-SHA-512"
      +            ],
      +            "type": "string"
      +          },
      +          "password": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "username": {
      +            "minLength": 1,
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "enabled",
      +          "mechanism",
      +          "username",
      +          "password"
      +        ],
      +        "type": "object"
      +      },
      +      "tls": {
      +        "additionalProperties": false,
      +        "description": "TLS settings. Omit tls to disable it.",
      +        "properties": {
      +          "enabled": {
      +            "const": true,
      +            "type": "boolean"
      +          },
      +          "verify_certificate": {
      +            "type": "boolean"
      +          },
      +          "verify_hostname": {
      +            "type": "boolean"
      +          }
      +        },
      +        "required": [
      +          "enabled"
      +        ],
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "bootstrap_servers"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "auth": {
      +        "description": "NATS credentials. Passwords, tokens, and NKey seeds are secrets. Omit for an unauthenticated broker.",
      +        "oneOf": [
      +          {
      +            "additionalProperties": false,
      +            "properties": {
      +              "password": {
      +                "minLength": 1,
      +                "type": "string"
      +              },
      +              "strategy": {
      +                "const": "user_password",
      +                "type": "string"
      +              },
      +              "user": {
      +                "minLength": 1,
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "strategy",
      +              "user",
      +              "password"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "additionalProperties": false,
      +            "properties": {
      +              "strategy": {
      +                "const": "token",
      +                "type": "string"
      +              },
      +              "token": {
      +                "minLength": 1,
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "strategy",
      +              "token"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "additionalProperties": false,
      +            "properties": {
      +              "nkey": {
      +                "minLength": 1,
      +                "type": "string"
      +              },
      +              "seed": {
      +                "minLength": 1,
      +                "type": "string"
      +              },
      +              "strategy": {
      +                "const": "nkey",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "strategy",
      +              "nkey",
      +              "seed"
      +            ],
      +            "type": "object"
      +          }
      +        ]
      +      },
      +      "batch": {
      +        "additionalProperties": false,
      +        "description": "Optional HTTP delivery batch settings.",
      +        "properties": {
      +          "max_events": {
      +            "maximum": 100000,
      +            "minimum": 1,
      +            "type": "integer"
      +          },
      +          "timeout_secs": {
      +            "exclusiveMinimum": 0,
      +            "maximum": 60,
      +            "type": "number"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "servers": {
      +        "description": "Comma-separated nats:// or tls:// server URLs, without embedded credentials.",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "tls": {
      +        "additionalProperties": false,
      +        "description": "Standard TLS with certificate and hostname verification. tls:// URLs also enable TLS.",
      +        "properties": {
      +          "enabled": {
      +            "const": true,
      +            "type": "boolean"
      +          }
      +        },
      +        "required": [
      +          "enabled"
      +        ],
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "servers"
      +    ],
      +    "type": "object"
      +  }
      +]
    • addedInput schema / properties / settings / description
      Added value: +"Settings must match type: bootstrap_servers for kafka; servers and optional auth for nats."
    • removedInput schema / properties / settings / properties
      Removed value: -{
      -  "auto_offset_reset": {
      -    "description": "Offset policy when the consumer group has no committed offset. Defaults to largest.",
      -    "enum": [
      -      "largest",
      -      "smallest"
      -    ],
      -    "type": "string"
      -  },
      -  "batch": {
      -    "additionalProperties": false,
      -    "description": "Optional HTTP delivery batch settings.",
      -    "properties": {
      -      "max_events": {
      -        "maximum": 100000,
      -        "minimum": 1,
      -        "type": "integer"
      -      },
      -      "timeout_secs": {
      -        "exclusiveMinimum": 0,
      -        "maximum": 60,
      -        "type": "number"
      -      }
      -    },
      -    "type": "object"
      -  },
      -  "bootstrap_servers": {
      -    "description": "Kafka bootstrap server addresses.",
      -    "minLength": 1,
      -    "type": "string"
      -  },
      -  "sasl": {
      -    "additionalProperties": false,
      -    "description": "SASL credentials. Omit sasl for an unauthenticated Kafka connection.",
      -    "properties": {
      -      "enabled": {
      -        "const": true,
      -        "type": "boolean"
      -      },
      -      "mechanism": {
      -        "enum": [
      -          "PLAIN",
      -          "SCRAM-SHA-256",
      -          "SCRAM-SHA-512"
      -        ],
      -        "type": "string"
      -      },
      -      "password": {
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "username": {
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "enabled",
      -      "mechanism",
      -      "username",
      -      "password"
      -    ],
      -    "type": "object"
      -  },
      -  "tls": {
      -    "additionalProperties": false,
      -    "description": "TLS settings. Omit tls to disable it.",
      -    "properties": {
      -      "enabled": {
      -        "const": true,
      -        "type": "boolean"
      -      },
      -      "verify_certificate": {
      -        "type": "boolean"
      -      },
      -      "verify_hostname": {
      -        "type": "boolean"
      -      }
      -    },
      -    "required": [
      -      "enabled"
      -    ],
      -    "type": "object"
      -  }
      -}
    • removedInput schema / properties / settings / required
      Removed value: -[
      -  "bootstrap_servers"
      -]
    • removedInput schema / properties / settings / type
      Removed value: -"object"
    • removedInput schema / properties / type / const
      Removed value: -"kafka"
    • addedInput schema / properties / type / enum
      Added value: +[
      +  "kafka",
      +  "nats"
      +]
  2. Addedv0.3.2

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: consumption begins only after the runtime applies the connector, Kafka destinations get independent consumer groups with group_id auto-generated if omitted, and NATS requires an existing durable pull consumer with explicit acks. It also discloses the organization-admin auth requirement, non-idempotent creation, and a reconcile-by-name recovery path, which aligns with (rather than contradicts) idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Bold section labels (Purpose, Behavior, Auth, Safety, Reliability) front-load the intent and make scanning easy for a complex mutation tool. The Safety checklist is long relative to its informational yield, but each item maps to a real pre-flight check rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, dual-mode creation tool with no output schema and partial schema coverage, the description covers purpose, type-dependent shape, auth, secret handling, and non-idempotent retry reconciliation. An agent can call this correctly without opening any documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%, and the description compensates by explaining that settings and destination fields must match the selected type, that omitting group_id generates an independent consumer group, and that nats_stream/nats_consumer must name pre-existing objects. It does not cover the organization and cluster parameters beyond the confirmation checklist, so a small gap remains.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create an active Kafka or NATS JetStream connector with one or more destinations') and scopes it by type-matching requirements. It does not name the sibling that handles later destination additions (add-connector-destination), so an agent must infer that boundary rather than being routed to it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when the tool applies (new connector, settings matching type) plus a concrete exclusion of one alternative behavior: 'RawTree does not create streams or consumers,' pushing the agent to pre-provision those. It also names list-connectors as the reconciliation path when a response is ambiguous, though it never states when not to create a connector at all.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.