Skip to content
Sec-Gemini

BYOT Skills

These skills teach AI assistants (Claude Code, Gemini CLI, or any MCP-compatible agent) how to use Sec-Gemini’s BYOT (Bring Your Own Tool) system. Copy the skill content into a file and upload it, or save it locally for your AI assistant to reference.

How to Use These Skills

Section titled “How to Use These Skills”

Upload to Sec-Gemini

Section titled “Upload to Sec-Gemini”
from sec_gemini import SecGemini


async with SecGemini(api_key="YOUR_KEY") as client:
    with open("byot-usage-skill.md") as f:
        await client.skills.upload(name="byot-usage-skill.md", content=f.read())

Save Locally

Section titled “Save Locally”

Save as a markdown file in your project for your AI assistant to reference directly.

Skill: BYOT Usage

Section titled “Skill: BYOT Usage”

This skill teaches an AI assistant how to start, manage, and use BYOT to connect local tools to the Sec-Gemini cloud agent.

---
name: sec-gemini-byot-usage
description: How to use BYOT to connect local tools to the Sec-Gemini cloud agent
---


## BYOT (Bring Your Own Tools)


BYOT connects tools on your local machine to the Sec-Gemini cloud agent via an outbound gRPC tunnel. No inbound ports required.


### CLI Quick Start


```bash
# Baseline tools only (35 tools: file, shell, Python, JavaScript, network)
sec-gemini-byot --api-key YOUR_KEY --use-baseline-tools


# Baseline + custom MCP
sec-gemini-byot --api-key YOUR_KEY --use-baseline-tools --additional-mcps ./my_tools.py


# Multiple custom MCPs
sec-gemini-byot --api-key YOUR_KEY --additional-mcps ./tools1.py ./tools2.py http://localhost:8000/sse
```


### CLI Flags


| Flag | Description |
|------|-------------|
| `--api-key` | (required) Sec-Gemini API key |
| `--name` | Client display name (default: `local`) |
| `--hub` | Hub URL (default: production) |
| `--use-baseline-tools` | Register 35 baseline tools |
| `--additional-mcps` | Extra MCPs as `.py` files or URLs |
| `--verbose` | DEBUG console output |


### Creating Custom Tools with FastMCP


```python
# my_tools.py
from fastmcp import FastMCP


mcp = FastMCP("my-tools")


@mcp.tool()
def my_custom_tool(query: str) -> str:
    """Description of what this tool does."""
    return f"Result for {query}"
```


Pass to BYOT: `--additional-mcps ./my_tools.py`


### Programmatic Usage


```python
from sec_gemini.byot.service import ByotService
from sec_gemini.tools import create_baseline_mcp


baseline, _ = create_baseline_mcp()
byot = ByotService(api_key="YOUR_KEY", name="my-client")
await byot.start(tools=[baseline])


# Check status
status = byot.status()  # .state, .tool_count, .tools


# Stop
await byot.stop()
```


### Baseline Tool Categories


**File (9):** `read_file`, `write_file`, `edit_file`, `list_directory`, `grep`, `find_files`, `file_info`, `remove_file`, `remove_directory`


**Shell (6):** `bash`, `run_background`, `list_background`, `peek_background`, `stop_background`, `read_background`


**Python Execution (4):** `python_exec`, `python_install`, `python_packages`, `python_find_packages`


**JavaScript Execution (4):** `javascript_exec`, `javascript_install`, `javascript_packages`, `javascript_find_packages`


**Network (12):** `dns_lookup`, `whois_lookup`, `tcp_port_check`, `tcp_send`, `ping`, `traceroute`, `fetch_http`, `grep_http`, `http_headers`, `fetch_file`, `ssl_check`, `check_email_security`


### Important Notes


- File writes require a prior `read_file` (sha256 guard prevents blind overwrites).
- BYOT auto-retries on connection drops (4s-30s backoff, 10 attempts max).
- Logs go to `~/.config/sec-gemini/logs/byot.log`.
- The TUI manages BYOT automatically when local tools are configured.

Skill: Custom MCP Development

Section titled “Skill: Custom MCP Development”

This skill teaches an AI assistant how to create and test custom FastMCP tools for use with BYOT.

---
name: custom-mcp-development
description: How to create custom FastMCP tools for Sec-Gemini BYOT
---


## Creating Custom MCP Tools for BYOT


### Basic Structure


Every custom MCP file needs a `FastMCP` instance with `@mcp.tool()` decorated functions:


```python
from fastmcp import FastMCP


mcp = FastMCP("tool-server-name")


@mcp.tool()
def tool_name(param1: str, param2: int = 10) -> str:
    """Clear description of what this tool does. The agent reads this."""
    # Implementation
    return "result"
```


### Best Practices


1. **Descriptive docstrings** -- The agent uses the docstring to decide when to call your tool.
2. **Type hints** -- Use Python type hints for all parameters and return values.
3. **String returns** -- Return strings. The agent processes text.
4. **Error handling** -- Return error descriptions as strings rather than raising exceptions.
5. **Default parameters** -- Use defaults for optional configuration.


### Example: Internal API Integration


```python
from fastmcp import FastMCP
import httpx


mcp = FastMCP("internal-api")


@mcp.tool()
def query_siem(query: str, time_range: str = "24h") -> str:
    """Search the internal SIEM for security events matching the query."""
    resp = httpx.get(
        "https://siem.internal/api/search",
        params={"q": query, "range": time_range},
        headers={"Authorization": f"Bearer {os.environ['SIEM_TOKEN']}"},
    )
    return resp.text


@mcp.tool()
def get_asset_info(hostname: str) -> str:
    """Look up asset information from the CMDB."""
    resp = httpx.get(f"https://cmdb.internal/api/assets/{hostname}")
    if resp.status_code == 404:
        return f"Asset {hostname} not found in CMDB"
    return resp.text
```


### Testing Locally


```bash
# Start BYOT with your tool
sec-gemini-byot --api-key KEY --additional-mcps ./my_tools.py --verbose


# The verbose flag shows tool registrations and call/response payloads
```


### Combining Multiple Tool Files


```bash
sec-gemini-byot --api-key KEY \
    --use-baseline-tools \
    --additional-mcps ./siem_tools.py ./vuln_scanner.py ./internal_api.py
```