getTaggedEntities

Instructions

Implementation Reference

• src/tools/getTaggedEntities.ts:47-77 (handler)

  The handler function that executes the 'getTaggedEntities' tool logic. It makes a GET request to /tags/{slug}/entities with optional query parameters (limit, direction, cursor, entityType) and returns the result.

  export async function handler(
    args: z.infer<typeof parameters>,
    extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext }
  ): Promise<CallToolResult> {
    try {
      const endpoint = `/tags/${args.slug}/entities`;
      const query = new URLSearchParams();
      if (args.limit !== undefined) query.set('limit', String(args.limit));
      if (args.direction !== undefined) query.set('direction', String(args.direction));
      if (args.cursor !== undefined) query.set('cursor', String(args.cursor));
      if (args.entityType !== undefined) query.set('entityType', String(args.entityType));
      const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint;
      const options: any = {
        headers: extra.headers,
      };
      const result = await extra.client.get(url, options);
      return {
        content: [
          {
            type: 'text',
            text: `${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`,
          },
        ],
      };
    } catch (e: unknown) {
      if (e instanceof McpError) {
        throw e;
      }
      throw asMcpError(e);
    }
  }

• src/tools/getTaggedEntities.ts:9-38 (schema)

  Zod schema defining the input parameters for getTaggedEntities: slug (string, regex validated), limit (number, max 50), direction (asc/desc), cursor (optional string), entityType (optional enum: api/collection/workspace).

  export const parameters = z.object({
    slug: z
      .string()
      .regex(new RegExp('^[a-z][a-z0-9-]*[a-z0-9]+$'))
      .min(2)
      .max(64)
      .describe("The tag's ID within a team or individual (non-team) user scope."),
    limit: z
      .number()
      .int()
      .lte(50)
      .describe('The maximum number of tagged elements to return in a single call.')
      .default(10),
    direction: z
      .enum(['asc', 'desc'])
      .describe(
        "The ascending (`asc`) or descending (`desc`) order to sort the results by, based on the time of the entity's tagging."
      )
      .default('desc'),
    cursor: z
      .string()
      .describe(
        'The cursor to get the next set of results in the paginated response. If you pass an invalid value, the API only returns the first set of results.'
      )
      .optional(),
    entityType: z
      .enum(['api', 'collection', 'workspace'])
      .describe('Filter results for the given entity type.')
      .optional(),
  });

• src/tools/getTaggedEntities.ts:39-45 (schema)

  Annotations for the tool: title, readOnlyHint (true), destructiveHint (false), idempotentHint (true).

  export const annotations = {
    title:
      '**Requires an Enterprise plan.** Tagging is only available on Postman Enterprise plans. This tool returns a 404 error on Free, Basic, and Professional accounts.',
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
  };

• src/enabledResources.ts:136-136 (registration)

  getTaggedEntities is registered in the 'full' enabled resources list (line 136) and also in the 'minimal' list (line 199).

  'getTaggedEntities',

• src/tools/utils/toolHelpers.ts:10-13 (helper)

  The asMcpError helper utility used by the handler to wrap errors into McpError format.

  export function asMcpError(error: unknown): McpError {
    const cause = (error as any)?.cause ?? String(error);
    return new McpError(ErrorCode.InternalError, cause);
  }