feat: Skills Architecture v3.2.0 - New Tools + Self-Documenting URLs

[jeffzwang]

Summary

This PR introduces a "Skills Architecture" for the Exa MCP server - making it easier for users to leverage Exa's full power through smart defaults, self-documenting configuration, and workflow-specific guidance.

The Problem We Were Solving

1. Users don't know which tools to enable for their use case
2. Simple search doesn't expose Exa's full power (categories, domain filtering, highlights, summaries, subpages)
3. No guidance on HOW to combine tools for real workflows (company research, GTM, academic research)

Design Philosophy

"Simple MCP + Smart Docs + Full Power"

• MCP = Zero config default, all tools available when needed
• Docs = Comprehensive reference that humans copy from and LLMs parse
• Skills = Optional workflow guides that teach WHEN and HOW to use powerful params

No modes. One install, everything works. Skills teach usage patterns.

---

Key Design Decisions

1. Two Search Tools (Same Endpoint)

We needed TWO tools calling the SAME /search endpoint:

• web_search_exa - Simple params for everyday use (existing)
• web_search_advanced - Full Exa API surface for building skills (NEW)

Why not just add params to the existing tool?

• Keeps simple tool simple (3 params vs 25+)
• Advanced users get full control without cluttering basic experience
• Skills can reference the advanced tool specifically

Naming research: Consulted multiple AI models. Chose web_search_advanced to keep web_search_ prefix consistent - the _advanced suffix clearly signals "more options."

2. Self-Documenting URL Pattern

Instead of hidden config, the URL itself shows what's ON and OFF:

# NEW pattern (preferred)
--enabled=web_search_exa,get_code_context_exa

# LEGACY pattern (still works)
--tools=web_search_exa,get_code_context_exa

Server echoes full state on startup:

Exa MCP loaded - ENABLED: web_search_exa,get_code_context_exa | DISABLED: web_search_advanced,...

Benefits:

• LLM reads URL → knows exactly what's available
• Human reads URL → knows what they're getting
• Want more tools? → Just edit the URL
• Full transparency, no hidden config

3. Skills Instead of Modes

We considered "modes" (research mode, GTM mode) but rejected it.

Skills are better because:

1. MCP always has full capability - skills just teach patterns
2. Users can mix and match - not locked into one mode
3. Skills are documentation that Claude reads contextually
4. No code changes needed to add new workflows

---

What's New

New Tools (4)

Tool	Endpoint	Purpose
web_search_advanced	/search	Full API: categories, domains, dates, highlights, summaries, subpages
find_similar_exa	/findSimilar	Find pages similar to a URL
answer_exa	/answer	Direct Q&A with citations
crawl_urls_exa	/contents	Batch URL crawling with extraction options

Smart Docs (docs/install.md)

• Platform-specific install configs
• Configuration presets (Basic, Power User, Company Research, GTM, Full Power)
• Complete parameter reference
• Example usage patterns

Claude Code Skills (5)

Skill	Use Case
exa-company-research	Company intel, competitors, financials
exa-people-research	LinkedIn + web for people research
exa-gtm	Sales prospecting, pre-call research
exa-research-paper	Academic literature review
exa-web-chunker	Content extraction, documentation harvesting

---

Key Insight

The power isn't in having more tools - it's in knowing WHEN to use which params:

• category: "company" vs category: "research paper"
• includeDomains for trusted sources
• enableHighlights + highlightsQuery for scanning
• subpages for documentation sites

Skills encode this knowledge so Claude can apply it automatically.

---

Test Plan

• Verify --enabled=web_search_exa only registers that tool
• Verify legacy --tools=web_search_exa still works
• Test web_search_advanced with category filters
• Test find_similar_exa endpoint
• Test answer_exa endpoint
• Test crawl_urls_exa batch crawling
• Verify skills load in Claude Code

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
exa-mcp-server	Error		Jan 6, 2026 11:37pm