SignNow MCP Server

Instructions

Implementation Reference

• src/sn_mcp_server/tools/signnow.py:458-503 (handler)

  MCP tool handler and registration for create_embedded_sending_from_template. Thin wrapper that authenticates and delegates to core helper.

  @mcp.tool(
      name="create_embedded_sending_from_template",
      description=(
          "Create document/group from template and create embedded sending immediately. "
          "This tool is ONLY for templates and template groups. "
          "If you have document or document_group, use the alternative tool: create_embedded_sending"
      ),
      tags=["template", "template_group", "document", "document_group", "send_invite", "embedded", "workflow"],
  )
  async def create_embedded_sending_from_template(
      ctx: Context,
      entity_id: Annotated[str, Field(description="ID of the template or template group")],
      entity_type: Annotated[
          Literal["template", "template_group"] | None,
          Field(description="Type of entity: 'template' or 'template_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type."),
      ] = None,
      name: Annotated[str | None, Field(description="Optional name for the new document or document group")] = None,
      redirect_uri: Annotated[str | None, Field(description="Optional redirect URI after completion")] = None,
      redirect_target: Annotated[str | None, Field(description="Optional redirect target: 'self' (default), 'blank'")] = None,
      link_expiration: Annotated[int | None, Field(ge=14, le=45, description="Optional link expiration in days (14-45)")] = None,
      type: Annotated[Literal["manage", "edit", "send-invite"] | None, Field(description="Type of sending step: 'manage', 'edit', or 'send-invite'")] = None,
  ) -> CreateEmbeddedSendingFromTemplateResponse:
      """Create document or document group from template and create embedded sending immediately.
  
      This tool is ONLY for templates and template groups.
      If you have document or document_group, use the alternative tool: create_embedded_sending
  
      This tool combines two operations:
      1. Creates a document/group from template using create_from_template
      2. Creates an embedded sending for the created entity using create_embedded_sending
  
      Args:
          entity_id: ID of the template or template group
          entity_type: Type of entity: 'template' or 'template_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type.
          name: Optional name for the new document or document group
          redirect_uri: Optional redirect URI after completion
          redirect_target: Optional redirect target: 'self', 'blank', or 'self' (default)
          link_expiration: Optional link expiration in days (14-45)
          type: Type of sending step: 'manage', 'edit', or 'send-invite'
  
      Returns:
          CreateEmbeddedSendingFromTemplateResponse with created entity info and embedded sending details
      """
      token, client = _get_token_and_client(token_provider)
  
      return await _create_embedded_sending_from_template(entity_id, entity_type, name, redirect_uri, redirect_target, link_expiration, type, token, client, ctx)

• src/sn_mcp_server/tools/embedded_sending.py:107-172 (helper)

  Core helper function implementing the logic: create document/group from template, then create embedded sending link with progress reporting.

  async def _create_embedded_sending_from_template(
      entity_id: str,
      entity_type: Literal["template", "template_group"] | None,
      name: str | None,
      redirect_uri: str | None,
      redirect_target: str | None,
      link_expiration: int | None,
      sending_type: str | None,
      token: str,
      client: SignNowAPIClient,
      ctx: Context,
  ) -> CreateEmbeddedSendingFromTemplateResponse:
      """Private function to create document/group from template and create embedded sending immediately.
  
      Args:
          entity_id: ID of the template or template group
          entity_type: Type of entity: 'template' or 'template_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type.
          name: Optional name for the new document or document group
          redirect_uri: Optional redirect URI after completion
          redirect_target: Optional redirect target: 'self', 'blank', or 'self' (default)
          link_expiration: Optional link expiration in days (14-45)
          sending_type: Type of sending step: 'manage', 'edit', or 'send-invite'
          token: Access token for SignNow API
          client: SignNow API client instance
          ctx: FastMCP context for progress reporting
  
      Returns:
          CreateEmbeddedSendingFromTemplateResponse with created entity info and embedded sending details
      """
      # Report initial progress
      await ctx.report_progress(progress=1, total=3)
  
      # Import and use the create from template function directly
      from .create_from_template import _create_from_template
  
      # Use the imported function to create from template
      created_entity = _create_from_template(entity_id, entity_type, name, token, client)
  
      # Report progress after template creation
      await ctx.report_progress(progress=2, total=3)
  
      if created_entity.entity_type == "document_group":
          sending_response = _create_document_group_embedded_sending(client, token, created_entity.entity_id, redirect_uri, redirect_target, link_expiration, sending_type)
          # Report final progress after embedded sending creation
          await ctx.report_progress(progress=3, total=3)
          return CreateEmbeddedSendingFromTemplateResponse(
              created_entity_id=created_entity.entity_id,
              created_entity_type=created_entity.entity_type,
              created_entity_name=created_entity.name,
              sending_id=sending_response.sending_url,
              sending_entity=sending_response.sending_entity,
              sending_url=sending_response.sending_url,
          )
      else:
          # Create document embedded sending
          sending_response = _create_document_embedded_sending(client, token, created_entity.entity_id, redirect_uri, redirect_target, link_expiration, sending_type)
          # Report final progress after embedded sending creation
          await ctx.report_progress(progress=3, total=3)
          return CreateEmbeddedSendingFromTemplateResponse(
              created_entity_id=created_entity.entity_id,
              created_entity_type=created_entity.entity_type,
              created_entity_name=created_entity.name,
              sending_id=sending_response.sending_url,
              sending_entity=sending_response.sending_entity,
              sending_url=sending_response.sending_url,
          )

• src/sn_mcp_server/tools/models.py:244-261 (schema)

  Pydantic input schema for the tool request parameters.

  class CreateEmbeddedSendingFromTemplateRequest(BaseModel):
      """Request model for creating document/group from template and creating embedded sending immediately."""
  
      entity_id: str = Field(..., description="ID of the template or template group")
      entity_type: str | None = Field(None, description="Type of entity: 'template' or 'template_group' (optional)")
      name: str | None = Field(None, description="Optional name for the new document or document group")
      redirect_uri: str | None = Field(None, description="Optional redirect URI after completion")
      redirect_target: str | None = Field(None, description="Optional redirect target: 'self', 'blank', or 'self' (default)")
      link_expiration: int | None = Field(None, ge=14, le=45, description="Optional link expiration in days (14-45)")
      type: str | None = Field(None, description="Type of sending step: 'manage', 'edit', or 'send-invite'")
  
      def model_dump(self, **kwargs: Any) -> dict[str, Any]:
          """Override model_dump to exclude redirect_target if redirect_uri is not provided."""
          data = super().model_dump(**kwargs)
          if (not self.redirect_uri or not self.redirect_uri.strip()) and "redirect_target" in data:
              del data["redirect_target"]
          return data

• src/sn_mcp_server/tools/models.py:263-272 (schema)

  Pydantic output schema for the tool response.

  class CreateEmbeddedSendingFromTemplateResponse(BaseModel):
      """Response model for creating document/group from template and creating embedded sending immediately."""
  
      created_entity_id: str = Field(..., description="ID of the created document or document group")
      created_entity_type: str = Field(..., description="Type of created entity: 'document' or 'document_group'")
      created_entity_name: str = Field(..., description="Name of the created entity")
      sending_id: str = Field(..., description="ID of the created embedded sending")
      sending_entity: str = Field(..., description="Type of sending entity: 'document', 'document_group', or 'invite'")
      sending_url: str = Field(..., description="URL for the embedded sending")