Skip to main content
Glama
thenavidm

substack-mcp

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Create a draft

create_draft

Create a new private Substack draft post; it stays private until published. Returns the draft ID required by other draft tools.

Instructions

Create a new draft post. The draft is private until you publish it. Returns the draft id, which every other draft tool takes.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyNoPost body. Markdown by default. Supported: headings, bold, italic, inline code, strikethrough, links, images, nested lists (any depth, ordered and unordered mixed), fenced code blocks with a language, blockquotes and horizontal rules. Two things worth knowing: - A line containing only a YouTube, X, Spotify or Vimeo URL becomes a real embedded player, not a link. Put the URL inside a sentence if you want a plain link. - Write <paywall> on its own line to mark where the paywall starts. Everything after it is for paying subscribers only. One per post. Markdown tables have no equivalent in Substack's editor, so they are preserved verbatim in a code block rather than being mangled.
typeNoPost type. 'newsletter' is the normal long-form post.newsletter
titleYesPost title. This is the headline, not an H1 in the body.
audienceNoWho can read it. 'everyone' is public, 'only_free' is any subscriber, 'only_paid' and 'founding' are paying tiers.everyone
subtitleNoOptional subtitle, shown under the title.
section_idNoPublish under a section. Call get_sections to find the id.
body_formatNoHow to read `body`. 'auto' detects it and is almost always right. Use 'prosemirror' to send a Substack document directly.
cover_imageNoCover image URL. Use upload_image first to get one hosted on Substack.
publicationNoWhich connected publication to act on, matched loosely against its hostname (for example 'example.substack.com' or just 'example'). Defaults to the first connected publication.
social_titleNoTitle used on social cards.
search_engine_titleNoSEO title, if different from the title.
search_engine_descriptionNoSEO meta description.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv3.0.1
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • removedInput schema / additionalProperties
      Removed value: -false
  2. First observedv2.1.1

TDQS

A3.8/5.0
Behavior4/5

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description still adds non-obvious context: the draft's visibility is private until published, and the call returns a draft id consumed by every other draft tool — useful for chaining calls.

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

Conciseness5/5

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

Three short sentences, front-loaded with the action, then the privacy behavior, then the return value. No filler and every clause earns its place.

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

Completeness4/5

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

With a fully documented schema and no output schema, the description supplies the one thing the schema cannot — that the return value is a draft id used by downstream draft tools. Complete enough to invoke correctly, though it could note the template-based alternative.

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% with 12 richly documented parameters including enums and markdown/body semantics, so the schema carries the full load. The description adds no parameter-level detail, which is the correct baseline of 3 when schema coverage is this high.

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 a new draft post' — which clearly separates it from update_draft, publish_draft, and delete_draft. It does not explicitly distinguish itself from the very similar create_draft_from_template sibling, so it stops short of a 5.

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

Usage Guidelines3/5

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

The workflow context is implied by 'the draft is private until you publish it,' which hints at the create-then-publish sequence. However, there is no explicit when-to-use guidance, no exclusions, and no pointer to create_draft_from_template as an alternative for templated creation.

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

Deploy Server

Other Tools