Example: Web Research

This example demonstrates how to set up a web research capability using Brave Search.

Overview

This configuration enables an agent to search the web for current information using the Brave Search API.

What You'll Need

A Brave Search API key (get one at brave.com/search/api)
Node.js installed (for the MCP server)

Configuration

providers:
  - cursor

skills:
  - id: web-researcher
    type: inline
    def:
      content: |
        ---
        name: web-researcher
        description: Search the web for information
        ---
        
        # Web Researcher
        
        Use the brave_search tool to find current information online.
        
        ## When to Use
        - User asks for current information
        - Need to verify facts
        - Research recent events or news
        - Find documentation or resources
        
        ## How to Use
        Call brave_search with a query string. The tool returns:
        - Search results with titles and URLs
        - Snippets from the top results
        - Relevance ranking
      requires:
        - brave_search

servers:
  - id: brave
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}

tools:
  - id: brave_search
    type: mcp
    def:
      server: "@brave"
      tool: brave_web_search

{
  "providers": ["cursor"],
  "skills": [
    {
      "id": "web-researcher",
      "type": "inline",
      "def": {
        "content": "---\nname: web-researcher\ndescription: Search the web for information\n---\n\n# Web Researcher\n\nUse the brave_search tool to find current information online.\n\n## When to Use\n- User asks for current information\n- Need to verify facts\n- Research recent events or news\n- Find documentation or resources\n\n## How to Use\nCall brave_search with a query string. The tool returns:\n- Search results with titles and URLs\n- Snippets from the top results\n- Relevance ranking",
        "requires": ["brave_search"]
      }
    }
  ],
  "servers": [
    {
      "id": "brave",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-brave-search",
        "env": {
          "BRAVE_API_KEY": "${BraveApiKey}"
        }
      }
    }
  ],
  "tools": [
    {
      "id": "brave_search",
      "type": "mcp",
      "def": {
        "server": "@brave",
        "tool": "brave_web_search"
      }
    }
  ]
}

Setup Steps

1. Get a Brave API Key

Visit brave.com/search/api
Sign up for a free account
Create an API key
Note the key for the next step

2. Create the Capabilities File

capa init

Then paste the configuration above into capabilities.yaml.

3. Install

capa install

CAPA will open a web UI asking for your BraveApiKey. Enter the API key from step 1.

Alternatively, use a .env file:

# Create .env file
echo "BraveApiKey=your-api-key-here" > .env

# Install with env file
capa install -e

4. Use It

In your MCP client (e.g., Cursor), the agent uses the on-demand workflow:

// Step 1: Activate the skill
setup_tools({"skills": ["web-researcher"]})

// Step 2: Use call_tool to invoke brave_search
call_tool({
  "name": "brave_search",
  "data": {
    "query": "latest developments in AI"
  }
})

Expected Behavior

Initial state: Agent sees setup_tools() and call_tool()
After setup: Agent receives brave_search schema and can invoke it via call_tool
Search results: Returns top web results with titles, URLs, and snippets

Note: If using toolExposure: expose-all, the agent sees brave_search directly and doesn't need setup_tools or call_tool.

Extending This Example

Add Web Scraping

Enhance with the ability to scrape content from search results:

tools:
  # ... existing brave_search tool ...
  
  - id: web_scrape
    type: command
    def:
      init:
        cmd: pip install beautifulsoup4 requests
      run:
        cmd: python -c "import requests; from bs4 import BeautifulSoup; print(BeautifulSoup(requests.get('{url}').text, 'html.parser').get_text())"
        args:
          - name: url
            type: string
            description: URL to scrape
            required: true

# Update skill requires
skills:
  - id: web-researcher
    type: inline
    def:
      requires:
        - brave_search
        - web_scrape
      content: |
        # ... update content to mention web_scrape ...

{
  "tools": [
    {
      "id": "web_scrape",
      "type": "command",
      "def": {
        "init": {
          "cmd": "pip install beautifulsoup4 requests"
        },
        "run": {
          "cmd": "python -c \"import requests; from bs4 import BeautifulSoup; print(BeautifulSoup(requests.get('{url}').text, 'html.parser').get_text())\"",
          "args": [
            {
              "name": "url",
              "type": "string",
              "description": "URL to scrape",
              "required": true
            }
          ]
        }
      }
    }
  ]
}