Skip to main content
Glama
Jeetanshu18

Tavily MCP Server

by Jeetanshu18
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

tavily-map

Create structured website maps to analyze site structure, discover content, and audit navigation paths for better understanding of web architecture.

Instructions

A powerful web mapping tool that creates a structured map of website URLs, allowing you to discover and analyze site structure, content organization, and navigation paths. Perfect for site audits, content discovery, and understanding website architecture.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesThe root URL to begin the mapping
max_depthNoMax depth of the mapping. Defines how far from the base URL the crawler can explore
max_breadthNoMax number of links to follow per level of the tree (i.e., per page)
limitNoTotal number of links the crawler will process before stopping
instructionsNoNatural language instructions for the crawler
select_pathsNoRegex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*)
select_domainsNoRegex patterns to select crawling to specific domains or subdomains (e.g., ^docs\.example\.com$)
allow_externalNoWhether to allow following links that go to external domains
categoriesNoFilter URLs using predefined categories like documentation, blog, api, etc

Implementation Reference

  • src/index.ts:512-527 (handler)
    Core implementation of the 'tavily-map' tool handler. Posts parameters to the Tavily map API endpoint ('https://api.tavily.com/map'), handles authentication and rate limit errors, and returns the API response containing the site map.
    async map(params: any): Promise<TavilyMapResponse> {
  try {
    const response = await this.axiosInstance.post(this.baseURLs.map, {
      ...params,
      api_key: API_KEY
    });
    return response.data;
  } catch (error: any) {
    if (error.response?.status === 401) {
      throw new Error('Invalid API key');
    } else if (error.response?.status === 429) {
      throw new Error('Usage limit exceeded');
    }
    throw error;
  }
}
  • src/index.ts:287-343 (schema)
    Input schema for the 'tavily-map' tool, defining parameters such as url (required), max_depth, max_breadth, limit, instructions, filtering options, and categories.
    inputSchema: {
  type: "object",
  properties: {
    url: { 
      type: "string", 
      description: "The root URL to begin the mapping"
    },
    max_depth: {
      type: "integer",
      description: "Max depth of the mapping. Defines how far from the base URL the crawler can explore",
      default: 1,
      minimum: 1
    },
    max_breadth: {
      type: "integer",
      description: "Max number of links to follow per level of the tree (i.e., per page)",
      default: 20,
      minimum: 1
    },
    limit: {
      type: "integer",
      description: "Total number of links the crawler will process before stopping",
      default: 50,
      minimum: 1
    },
    instructions: {
      type: "string",
      description: "Natural language instructions for the crawler"
    },
    select_paths: {
      type: "array",
      items: { type: "string" },
      description: "Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*)",
      default: []
    },
    select_domains: {
      type: "array",
      items: { type: "string" },
      description: "Regex patterns to select crawling to specific domains or subdomains (e.g., ^docs\\.example\\.com$)",
      default: []
    },
    allow_external: {
      type: "boolean",
      description: "Whether to allow following links that go to external domains",
      default: false
    },
    categories: {
      type: "array",
      items: { 
        type: "string",
        enum: ["Careers", "Blog", "Documentation", "About", "Pricing", "Community", "Developers", "Contact", "Media"]
      },
      description: "Filter URLs using predefined categories like documentation, blog, api, etc",
      default: []
    }
  },
  required: ["url"]
  • src/index.ts:284-345 (registration)
    Registration of the 'tavily-map' tool in the ListToolsRequestSchema handler, providing name, description, and input schema.
    {
  name: "tavily-map",
  description: "A powerful web mapping tool that creates a structured map of website URLs, allowing you to discover and analyze site structure, content organization, and navigation paths. Perfect for site audits, content discovery, and understanding website architecture.",
  inputSchema: {
    type: "object",
    properties: {
      url: { 
        type: "string", 
        description: "The root URL to begin the mapping"
      },
      max_depth: {
        type: "integer",
        description: "Max depth of the mapping. Defines how far from the base URL the crawler can explore",
        default: 1,
        minimum: 1
      },
      max_breadth: {
        type: "integer",
        description: "Max number of links to follow per level of the tree (i.e., per page)",
        default: 20,
        minimum: 1
      },
      limit: {
        type: "integer",
        description: "Total number of links the crawler will process before stopping",
        default: 50,
        minimum: 1
      },
      instructions: {
        type: "string",
        description: "Natural language instructions for the crawler"
      },
      select_paths: {
        type: "array",
        items: { type: "string" },
        description: "Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*)",
        default: []
      },
      select_domains: {
        type: "array",
        items: { type: "string" },
        description: "Regex patterns to select crawling to specific domains or subdomains (e.g., ^docs\\.example\\.com$)",
        default: []
      },
      allow_external: {
        type: "boolean",
        description: "Whether to allow following links that go to external domains",
        default: false
      },
      categories: {
        type: "array",
        items: { 
          type: "string",
          enum: ["Careers", "Blog", "Documentation", "About", "Pricing", "Community", "Developers", "Contact", "Media"]
        },
        description: "Filter URLs using predefined categories like documentation, blog, api, etc",
        default: []
      }
    },
    required: ["url"]
  }
},
  • src/index.ts:400-417 (handler)
    Dispatch handler case for 'tavily-map' in the CallToolRequestSchema. Parses arguments, calls the map method, formats the result, and returns the tool response.
    case "tavily-map":
  const mapResponse = await this.map({
    url: args.url,
    max_depth: args.max_depth,
    max_breadth: args.max_breadth,
    limit: args.limit,
    instructions: args.instructions,
    select_paths: Array.isArray(args.select_paths) ? args.select_paths : [],
    select_domains: Array.isArray(args.select_domains) ? args.select_domains : [],
    allow_external: args.allow_external,
    categories: Array.isArray(args.categories) ? args.categories : []
  });
  return {
    content: [{
      type: "text",
      text: formatMapResults(mapResponse)
    }]
  };
  • src/index.ts:589-601 (helper)
    Helper function to format the Tavily map API response into a human-readable string listing the base URL and mapped page URLs.
    function formatMapResults(response: TavilyMapResponse): string {
  const output: string[] = [];
  
  output.push(`Site Map Results:`);
  output.push(`Base URL: ${response.base_url}`);
  
  output.push('\nMapped Pages:');
  response.results.forEach((page, index) => {
    output.push(`\n[${index + 1}] URL: ${page}`);
  });
  
  return output.join('\n');
}

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It describes the tool as 'powerful' and for 'discovering and analyzing,' which implies it performs read-only operations, but doesn't specify behavioral traits like rate limits, authentication needs, or potential impacts on target websites. The description adds value by explaining the mapping purpose but lacks detailed behavioral disclosure.

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?

The description is appropriately sized and front-loaded: it starts with the core purpose, then elaborates on use cases. Every sentence earns its place by adding value without redundancy, making it efficient and well-structured.

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

Completeness3/5

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

Given the complexity (9 parameters, no annotations, no output schema), the description is somewhat complete but has gaps. It explains the tool's purpose and use cases well, but without annotations or output schema, it doesn't cover behavioral aspects or return values, leaving the agent to infer details from the schema alone.

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?

The schema description coverage is 100%, so the schema already documents all 9 parameters thoroughly. The description doesn't add specific parameter semantics beyond what the schema provides, such as explaining how 'categories' interact with mapping or the implications of 'max_depth.' Baseline 3 is appropriate since the schema does the heavy lifting.

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 description clearly states the tool's purpose: 'creates a structured map of website URLs' with specific verbs like 'discover and analyze site structure, content organization, and navigation paths.' It distinguishes from siblings like 'search' or 'extract' by focusing on mapping and structural analysis rather than general search or content extraction.

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?

The description provides clear context for when to use this tool: 'Perfect for site audits, content discovery, and understanding website architecture.' It doesn't explicitly mention when not to use it or name alternatives among siblings, but the context strongly implies it's for structural mapping rather than other tasks like searching or crawling without mapping.

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