Skip to main content
Glama

Create a channel

create_channel
Idempotent

Create a channel on an agent or an app. On an agent: a cron or heartbeat channel that wakes it on a schedule, a webhook channel that lets callers outside Valet reach it, or an mcp channel that serves it as an MCP server; what the agent does when it fires is the prompt file channels/.md in its source. On an app: a webhook, cron, or heartbeat channel whose deliveries Valet posts to path in the app, which only an app channel takes, so a private app takes webhooks and scheduled work without becoming public. Valet checks a webhook's signature before anything reaches the app, then posts the request as the sender sent it; a cron or heartbeat fire posts a small JSON body. Each delivery carries an X-Valet-Visitor token of kind channel and a delivery_key to treat as an idempotency key; return 2xx, and anything else retries for about a day. A webhook is signed by a secret held as an environment variable of the agent or app, and this never takes or returns a secret value: name it first in set_env_vars secret_names, whose request page the person opens to enter it, then pass its name as secret_name. A webhook without secret_name is refused. Creating a channel that already exists with the same kind and settings reports it and changes nothing; different settings are refused, so destroy it first. Slack and Telegram need a browser, so for them this gives the step to take and creates nothing. Otherwise it returns the channel's name and kind, its url, schedule, next fire time, secret_name, and prompt_path where they apply, and already when it existed. Requires connecting a Valet account.

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>",
      "channel": "<channel>",
      "channel_kind": "<channel_kind>"
    },
    "name": "create_channel"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesThe agent's or app's name, as list_services shows it. It is the one that will hold the channel.
pathNoWhere in the app Valet posts each delivery, such as /webhooks/stripe, so the app routes the channel's traffic to the handler that serves it.
channelYesWhat to call the channel, such as stripe-events, so later calls can attach, reauthorize, or destroy it by name. On an agent it also names the prompt file channels/<name>.md that says what to do when the channel fires.
org_nameNoThe Valet organization the agent or app belongs to. Omit to use the organization the account joined first.
scheduleNoFor cron, a schedule such as 'weekdays at 9:00am' or 'every 30 minutes' or a five-field cron expression. For heartbeat, an interval such as '15m', from 30s to 24h. Not used by other kinds.
timezoneNoFor cron, the place whose local time the schedule follows, as an IANA timezone such as America/New_York, so a 9:00 schedule fires at 9:00 there through daylight saving changes. Omit to read the schedule in UTC.
secret_nameNoNeeded for webhook. The name of an environment variable on this agent or app that holds the signing secret, named first in set_env_vars secret_names so the person enters it. Not used by other kinds.
channel_kindYesThe kind of channel: cron, heartbeat, webhook, mcp, slack, or telegram, as list_catalog_channels lists them. An app takes webhook, cron, or heartbeat only. Slack and Telegram give the step to take instead of creating anything.
verify_schemeNoFor webhook, how the sender signs: hmac-sha256 (the default), static-token for a sender that cannot sign, stripe, svix, slack, or mercury. This tool creates signed webhooks only, so there is no way to turn verification off.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / channel / description
      Previous value: -"The new channel's name, such as stripe-events. On an agent it also names the prompt file channels/<name>.md that says what to do when the channel fires."New value: +"What to call the channel, such as stripe-events, so later calls can attach, reauthorize, or destroy it by name. On an agent it also names the prompt file channels/<name>.md that says what to do when the channel fires."
    • changedInput schema / properties / path / description
      Previous value: -"The path in the app that handles each delivery, such as /webhooks/stripe."New value: +"Where in the app Valet posts each delivery, such as /webhooks/stripe, so the app routes the channel's traffic to the handler that serves it."
    • changedInput schema / properties / timezone / description
      Previous value: -"For cron, the IANA timezone the schedule is read in, such as America/New_York. Omit for UTC."New value: +"For cron, the place whose local time the schedule follows, as an IANA timezone such as America/New_York, so a 9:00 schedule fires at 9:00 there through daylight saving changes. Omit to read the schedule in UTC."
  2. Changed3 schema fields changed
    • changedInput schema / properties / channel / description
      Previous value: -"The new channel's name, such as stripe-events. On an agent it names the prompt file channels/<name>.md that says what to do when the channel fires."New value: +"The new channel's name, such as stripe-events. On an agent it also names the prompt file channels/<name>.md that says what to do when the channel fires."
    • changedInput schema / properties / name / description
      Previous value: -"The agent's or app's name, as list_services shows it: the one that will hold the channel."New value: +"The agent's or app's name, as list_services shows it. It is the one that will hold the channel."
    • changedInput schema / properties / path / description
      Previous value: -"The path in the app that handles each delivery, such as /webhooks/stripe. Needed for a channel on an app, and only there."New value: +"The path in the app that handles each delivery, such as /webhooks/stripe."
  3. Changed2 schema fields changed
    • changedInput schema / properties / path / description
      Previous value: -"Needed for a channel on an app, and only there: the path in the app that handles each delivery, such as /webhooks/stripe."New value: +"The path in the app that handles each delivery, such as /webhooks/stripe. Needed for a channel on an app, and only there."
    • changedInput schema / properties / timezone / description
      Previous value: -"For cron, an IANA timezone such as America/New_York. Omit for UTC."New value: +"For cron, the IANA timezone the schedule is read in, such as America/New_York. Omit for UTC."
  4. Changed1 schema field changed
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "agent": {
      -        "description": "Name of the agent or app that owns the channel.",
      -        "type": "string"
      -      },
      -      "already": {
      -        "description": "True when the channel already existed with the same kind and settings, so nothing changed. Absent when this call created it.",
      -        "type": "boolean"
      -      },
      -      "channel": {
      -        "description": "The channel's name, which list_channels and destroy_channel take.",
      -        "type": "string"
      -      },
      -      "channel_kind": {
      -        "description": "The channel's kind: cron, heartbeat, webhook, or mcp.",
      -        "type": "string"
      -      },
      -      "holder_kind": {
      -        "description": "app when the channel is on an app. Absent for a channel on an agent.",
      -        "type": "string"
      -      },
      -      "next_fire_at": {
      -        "description": "When the channel next fires, as an RFC 3339 time in UTC. Absent when no fire is scheduled and on a repeat call.",
      -        "type": "string"
      -      },
      -      "org": {
      -        "description": "Name of the Valet organization the call acted in.",
      -        "type": "string"
      -      },
      -      "path": {
      -        "description": "The path in the app that handles each delivery. Absent for a channel on an agent.",
      -        "type": "string"
      -      },
      -      "prompt_path": {
      -        "description": "The prompt file in the agent's source that tells it what to do when the channel fires. Absent for a channel on an app and on a repeat call.",
      -        "type": "string"
      -      },
      -      "schedule": {
      -        "description": "When the channel fires: the cron schedule, or every followed by the interval for a heartbeat. Absent for other kinds.",
      -        "type": "string"
      -      },
      -      "secret_name": {
      -        "description": "Name of the environment variable that holds a webhook's signing secret. Never the secret itself. Absent for other kinds and on a repeat call.",
      -        "type": "string"
      -      },
      -      "timezone": {
      -        "description": "IANA timezone of a cron schedule. Absent for other kinds and on a repeat call.",
      -        "type": "string"
      -      },
      -      "url": {
      -        "description": "The address callers post to, for a webhook or mcp channel on an agent. Absent for other channels.",
      -        "type": "string"
      -      },
      -      "warning": {
      -        "description": "A note about the new channel the caller should heed. Absent when there is none.",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "org",
      -      "agent",
      -      "channel",
      -      "channel_kind"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "org": {
      -        "description": "Name of the Valet organization the call acted in.",
      -        "type": "string"
      -      },
      -      "step": {
      -        "description": "What the person does in a browser, such as authorizing a service. Nothing has changed until they do it.",
      -        "type": "string"
      -      },
      -      "url": {
      -        "description": "Address of the page where the person finishes the step. Absent when the page has no address to give.",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "org",
      -      "step"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "agent": {
      +        "description": "Name of the agent or app that owns the channel.",
      +        "type": "string"
      +      },
      +      "already": {
      +        "description": "True when the channel already existed with the same kind and settings, so nothing changed. Absent when this call created it.",
      +        "type": "boolean"
      +      },
      +      "channel": {
      +        "description": "The channel's name, which list_channels and destroy_channel take.",
      +        "type": "string"
      +      },
      +      "channel_kind": {
      +        "description": "The channel's kind: cron, heartbeat, webhook, or mcp.",
      +        "type": "string"
      +      },
      +      "holder_kind": {
      +        "description": "app when the channel is on an app. Absent for a channel on an agent.",
      +        "type": "string"
      +      },
      +      "next_fire_at": {
      +        "description": "When the channel next fires, as an RFC 3339 time in UTC. Absent when no fire is scheduled and on a repeat call.",
      +        "type": "string"
      +      },
      +      "org": {
      +        "description": "Name of the Valet organization the call acted in.",
      +        "type": "string"
      +      },
      +      "path": {
      +        "description": "The path in the app that handles each delivery. Absent for a channel on an agent.",
      +        "type": "string"
      +      },
      +      "prompt_path": {
      +        "description": "The prompt file in the agent's source that tells it what to do when the channel fires. Absent for a channel on an app and on a repeat call.",
      +        "type": "string"
      +      },
      +      "schedule": {
      +        "description": "When the channel fires: the cron schedule, or every followed by the interval for a heartbeat. Absent for other kinds.",
      +        "type": "string"
      +      },
      +      "secret_name": {
      +        "description": "Name of the environment variable that holds a webhook's signing secret. Never the secret itself. Absent for other kinds and on a repeat call.",
      +        "type": "string"
      +      },
      +      "timezone": {
      +        "description": "IANA timezone of a cron schedule. Absent for other kinds and on a repeat call.",
      +        "type": "string"
      +      },
      +      "url": {
      +        "description": "The address callers post to, for a webhook or mcp channel on an agent. Absent for other channels.",
      +        "type": "string"
      +      },
      +      "warning": {
      +        "description": "A note about the new channel the caller should heed. Absent when there is none.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "org",
      +      "agent",
      +      "channel",
      +      "channel_kind"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "org": {
      +        "description": "Name of the Valet organization the call acted in.",
      +        "type": "string"
      +      },
      +      "step": {
      +        "description": "What the person does in a browser to finish creating the channel, such as installing a Slack app. Returned instead of a create result; no channel exists until they do it.",
      +        "type": "string"
      +      },
      +      "url": {
      +        "description": "Address of the page where the person finishes the step. Absent when the page has no address to give.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "org",
      +      "step"
      +    ],
      +    "type": "object"
      +  }
      +]
  5. Changed3 schema fields changed
    • changedInput schema / properties / channel / description
      Previous value: -"The new channel's name, such as stripe-events. It names the prompt file channels/<name>.md on an agent."New value: +"The new channel's name, such as stripe-events. On an agent it names the prompt file channels/<name>.md that says what to do when the channel fires."
    • changedInput schema / properties / name / description
      Previous value: -"The agent's or app's name."New value: +"The agent's or app's name, as list_services shows it: the one that will hold the channel."
    • changedInput schema / properties / secret_name / description
      Previous value: -"Needed for webhook. The name of an environment variable on this agent or app that holds the signing secret, set first with set_env_vars. Not used by other kinds."New value: +"Needed for webhook. The name of an environment variable on this agent or app that holds the signing secret, named first in set_env_vars secret_names so the person enters it. Not used by other kinds."
  6. Changed11 schema fields changed
    • changedInput schema / properties / channel / description
      Previous value: -"Required. The new channel's name: lowercase letters, digits, and hyphens."New value: +"The new channel's name, such as stripe-events. It names the prompt file channels/<name>.md on an agent."
    • addedInput schema / properties / channel / minLength
      Added value: +1
    • addedInput schema / properties / channel / pattern
      Added value: +"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
    • changedInput schema / properties / channel_kind / description
      Previous value: -"Required. One of cron, heartbeat, webhook, mcp, slack, or telegram, from list_catalog_channels. An app takes webhook, cron, or heartbeat only. Slack and Telegram give the step to take instead of creating anything."New value: +"The kind of channel: cron, heartbeat, webhook, mcp, slack, or telegram, as list_catalog_channels lists them. An app takes webhook, cron, or heartbeat only. Slack and Telegram give the step to take instead of creating anything."
    • changedInput schema / properties / name / description
      Previous value: -"Required. The agent's or app's name."New value: +"The agent's or app's name."
    • changedInput schema / properties / path / description
      Previous value: -"Required for a channel on an app, and only there: the path in the app that handles each delivery, such as /webhooks/stripe. It starts with / and is not under /__valet/."New value: +"Needed for a channel on an app, and only there: the path in the app that handles each delivery, such as /webhooks/stripe."
    • addedInput schema / properties / path / not
      Added value: +{
      +  "pattern": "^/__valet(/|$)"
      +}
    • addedInput schema / properties / path / pattern
      Added value: +"^/"
    • changedInput schema / properties / schedule / description
      Previous value: -"For cron, a schedule such as 'weekdays at 9:00am' or 'every 30 minutes' or a five-field cron expression. For heartbeat, an interval between 30s and 24h such as '15m'. Not used by other kinds."New value: +"For cron, a schedule such as 'weekdays at 9:00am' or 'every 30 minutes' or a five-field cron expression. For heartbeat, an interval such as '15m', from 30s to 24h. Not used by other kinds."
    • changedInput schema / properties / secret_name / description
      Previous value: -"Required for webhook. The name of an environment variable on this agent or app that holds the signing secret, set first with set_env_vars. Not used by other kinds."New value: +"Needed for webhook. The name of an environment variable on this agent or app that holds the signing secret, set first with set_env_vars. Not used by other kinds."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "agent": {
      +          "description": "Name of the agent or app that owns the channel.",
      +          "type": "string"
      +        },
      +        "already": {
      +          "description": "True when the channel already existed with the same kind and settings, so nothing changed. Absent when this call created it.",
      +          "type": "boolean"
      +        },
      +        "channel": {
      +          "description": "The channel's name, which list_channels and destroy_channel take.",
      +          "type": "string"
      +        },
      +        "channel_kind": {
      +          "description": "The channel's kind: cron, heartbeat, webhook, or mcp.",
      +          "type": "string"
      +        },
      +        "holder_kind": {
      +          "description": "app when the channel is on an app. Absent for a channel on an agent.",
      +          "type": "string"
      +        },
      +        "next_fire_at": {
      +          "description": "When the channel next fires, as an RFC 3339 time in UTC. Absent when no fire is scheduled and on a repeat call.",
      +          "type": "string"
      +        },
      +        "org": {
      +          "description": "Name of the Valet organization the call acted in.",
      +          "type": "string"
      +        },
      +        "path": {
      +          "description": "The path in the app that handles each delivery. Absent for a channel on an agent.",
      +          "type": "string"
      +        },
      +        "prompt_path": {
      +          "description": "The prompt file in the agent's source that tells it what to do when the channel fires. Absent for a channel on an app and on a repeat call.",
      +          "type": "string"
      +        },
      +        "schedule": {
      +          "description": "When the channel fires: the cron schedule, or every followed by the interval for a heartbeat. Absent for other kinds.",
      +          "type": "string"
      +        },
      +        "secret_name": {
      +          "description": "Name of the environment variable that holds a webhook's signing secret. Never the secret itself. Absent for other kinds and on a repeat call.",
      +          "type": "string"
      +        },
      +        "timezone": {
      +          "description": "IANA timezone of a cron schedule. Absent for other kinds and on a repeat call.",
      +          "type": "string"
      +        },
      +        "url": {
      +          "description": "The address callers post to, for a webhook or mcp channel on an agent. Absent for other channels.",
      +          "type": "string"
      +        },
      +        "warning": {
      +          "description": "A note about the new channel the caller should heed. Absent when there is none.",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "org",
      +        "agent",
      +        "channel",
      +        "channel_kind"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "org": {
      +          "description": "Name of the Valet organization the call acted in.",
      +          "type": "string"
      +        },
      +        "step": {
      +          "description": "What the person does in a browser, such as authorizing a service. Nothing has changed until they do it.",
      +          "type": "string"
      +        },
      +        "url": {
      +          "description": "Address of the page where the person finishes the step. Absent when the page has no address to give.",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "org",
      +        "step"
      +      ],
      +      "type": "object"
      +    }
      +  ],
      +  "type": "object"
      +}
  7. Changed6 schema fields changed
    • changedInput schema / properties / channel_kind / description
      Previous value: -"Required. One of cron, heartbeat, webhook, mcp, slack, or telegram, from list_catalog_channels. Slack and Telegram give the step to take instead of creating anything."New value: +"Required. One of cron, heartbeat, webhook, mcp, slack, or telegram, from list_catalog_channels. An app takes webhook, cron, or heartbeat only. Slack and Telegram give the step to take instead of creating anything."
    • changedInput schema / properties / name / description
      Previous value: -"Required. The agent's name."New value: +"Required. The agent's or app's name."
    • changedInput schema / properties / org_name / description
      Previous value: -"The Valet organization the agent belongs to. Omit to use the organization the account joined first."New value: +"The Valet organization the agent or app belongs to. Omit to use the organization the account joined first."
    • addedInput schema / properties / path
      Added value: +{
      +  "description": "Required for a channel on an app, and only there: the path in the app that handles each delivery, such as /webhooks/stripe. It starts with / and is not under /__valet/.",
      +  "type": "string"
      +}
    • changedInput schema / properties / secret_name / description
      Previous value: -"Required for webhook. The name of an environment variable on this agent that holds the signing secret, set first with set_env_vars. Not used by other kinds."New value: +"Required for webhook. The name of an environment variable on this agent or app that holds the signing secret, set first with set_env_vars. Not used by other kinds."
    • addedInput schema / properties / verify_scheme
      Added value: +{
      +  "description": "For webhook, how the sender signs: hmac-sha256 (the default), static-token for a sender that cannot sign, stripe, svix, slack, or mercury. This tool creates signed webhooks only, so there is no way to turn verification off.",
      +  "type": "string"
      +}
  8. Added

TDQS

A4.5/5.0
Behavior5/5

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

Far beyond the annotations, it discloses delivery mechanics (X-Valet-Visitor token of kind channel, delivery_key as idempotency key, 2xx required or retries for about a day), that signature checks happen before the app sees anything, that no secret value is ever taken or returned, and that re-creating an identical channel is a no-op while conflicting settings are refused. The idempotentHint=true annotation is corroborated rather than contradicted by the 'already when it existed' return behavior.

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

Conciseness3/5

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

The purpose is front-loaded, but the body is a single dense block of semicolon-chained clauses covering delivery protocol, secret provisioning, idempotency, and refusal rules. Every fact is relevant, yet the lack of separation makes it hard to scan and several clauses run long.

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 9-parameter, open-world creation tool with an output schema, the definition covers prerequisites, per-kind behavior, failure modes, and return contents. Nothing an agent needs in order to call it successfully or interpret the result is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the parameter docs are already detailed (schedule formats, IANA timezone, verify_scheme options), so the baseline is 3. The description adds only a little beyond that, chiefly the refusal rule for a webhook without secret_name and the two-step set_env_vars flow, both of which the schema also covers.

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

Purpose5/5

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

The opening sentence names a specific verb and resource ('Create a channel') and immediately splits the resource into its two hosting contexts (agent vs app) with the concrete kinds each supports. An agent can distinguish this from siblings like attach_channel or create_connector without opening the schema.

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

Usage Guidelines5/5

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

It states prerequisites explicitly ('Requires connecting a Valet account', 'name it first in set_env_vars secret_names... then pass its name as secret_name'), gives when-not conditions (Slack and Telegram only return a step and create nothing; app channels accept only webhook, cron, heartbeat; a webhook without secret_name is refused), and prescribes the destroy-first path when settings differ. That is a near-complete decision rule for invoking it correctly.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources