Venn - Secure Universal MCP (Google Workspace, Jira, GitHub, and more)

Search, describe, and execute enterprise tools (Jira, Salesforce, Gmail, Slack, Google Calendar, Google Drive, GitHub, Notion, Box, etc.) via the Venn tool-router REST API. Use when the user asks to: (1) query or search data in enterprise SaaS apps, (2) create, update, or manage records (tickets, emails, calendar events, documents), (3) automate multi-step workflows across connected services, or (4) check what integrations are available. Triggers on phrases like "check my Jira tickets", "search Slack", "create a Salesforce lead", "find emails from X", "sync data between apps", or any reference to connected enterprise tools.

Venn Tools

Connect to enterprise SaaS tools through the Venn platform REST API.

Setup

This skill is gated on VENN_API_KEY — it won't appear until the key is set.

1. Get your API key from app.venn.ai

2. Add it to the OpenClaw .env file:

   echo 'VENN_API_KEY=your-api-key-here' >> ~/.openclaw/.env
   

3. Restart the gateway (picks up the new env on start):

   openclaw gateway restart
   

   Or, for zero-downtime reload without restart:

   openclaw secrets reload
   

Alternatively, use the interactive secrets helper:

openclaw secrets configure --skip-provider-setup

Sandboxed agents: The .env file injects into the host process only. For sandboxed (Docker) sessions, also add VENN_API_KEY to agents.defaults.sandbox.docker.env in openclaw.json, or bake it into your custom sandbox image.

Configuration

• VENN_API_KEY (required) — your Venn API key
• VENN_API_URL (optional) — defaults to https://app.venn.ai/api/tooliq

Request Format

All requests use POST with JSON. Examples below use this shorthand:

# Full form (shown once):
VENN_URL="${VENN_API_URL:-https://app.venn.ai/api/tooliq}"
curl -s -X POST "${VENN_URL}/tools/search" \
  -H "Authorization: Bearer ${VENN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

# Shorthand (used throughout):
# POST /tools/search {"query": "..."}

---

1. Discovery

List connected servers

# POST /tools/help
{"action": "list_servers"}

Returns result.servers[] with server_id, name, and connection_status.

Other help actions:

• getting_started — onboarding guidance
• connector_help — info on connectors (pass server_id for specific one)
• auth_helper — OAuth re-auth URL for disconnected server (requires server_id)

Search for tools

# POST /tools/search
{"query": "jira search issues", "limit": 10}

Returns result.candidates[] with server_id, tool_name, short_description, and (for top results) full inputSchema.

Additional parameters: offset, min_score (0–1, default 0.3), min_results (default 5), include_skills (default true).

Search strategy — broad first, narrow if needed:

1. Start with the full task description in natural language (skills match better):

   • "create a linear ticket and set it to in progress"
   • "sync salesforce contacts to a google sheet"

2. If no skill matches, decompose into one search per platform + action:

   • "query salesforce contacts" + "create google sheets row"

3. For simple single-platform tasks, search directly: "create salesforce lead"

Splitting rules:

• 1 search = 1 platform + 1 action (no single tool handles compound actions)
• Always include the app name in each query
• "recap"/"summarize" → search the platform, then present
• "cross-reference"/"compare" → search each platform, combine results
• "sync X to Y" → search source, then destination

If no results, try alternate names:

• "jira" → "atlassian"
• "google docs" → "google-drive" or "googledocs"
• "github" → "github-cloud"

Choosing from results:

• Read operations → prefer broad query tools over get-by-ID
• Create/update → look for specific create/update endpoints
• If a skill appears (type="skill"), prefer it over assembling tools
• inputSchema is the source of truth for parameter names — NEVER guess

For platform-specific query syntax (JQL, SOQL, Gmail search), see references/query-syntax.md.

Describe a tool

# POST /tools/describe
{"tools": [{"server_id": "SERVER_ID", "tool_name": "TOOL_NAME"}]}

Supports batch requests. Returns result.results[] with inputSchema, description, and write_operation type.

---

2. Execution

Schema adherence (most common source of errors)

1. Copy parameter names verbatim from inputSchema — casing matters

   • Schema says maxResults → use maxResults, NOT max_results

2. Match data types exactly:

   • "type": "string" → "10", NOT 10
   • "type": "integer" → 10, NOT "10"
   • "type": "array" → ["value"], NOT "value"
   • "type": "object" → {"key": "value"}, NOT "key=value"

3. Include all required fields. Do not add fields not in the schema.

Execute a single tool

# POST /tools/execute
{"server_id": "SERVER_ID", "tool_name": "TOOL_NAME", "tool_args": {...}}

Translating user intent into values (infer rather than ask):

• "recent tickets" → reasonable date range (e.g., last 7 days)
• "my emails" → userId: "me"
• "the main channel" → search for it by name first
• "current sprint" → the active sprint

This applies to values only — parameter names and types must come from inputSchema.

Data integrity: NEVER fabricate data. Only present what appears in actual responses.

Handling links: For create/edit operations, surface clickable URLs from fields like url, link, href, web_url, permalink, html_url. Present as [Resource Name](url).

Execute a workflow (multi-step)

Chain multiple tool calls in a Python sandbox:

# POST /tools/execute-workflow
{
  "code": "results = call_tool(\"atlassian\", \"searchByJQL\", jql=\"assignee = currentUser() AND status != Done\")\nreturn [{\"key\": i[\"key\"], \"summary\": i[\"fields\"][\"summary\"]} for i in results.get(\"issues\", [])]",
  "timeout": 180
}

When to use workflows:

• Multiple tool calls in sequence
• Parallel execution across services
• Data processing, iteration, or transformation

Code rules:

• Follow schema adherence rules above
• Write flat, inline code — no helper functions
• Code must return a value; extract only needed fields
• Check for errors: if isinstance(result, dict) and "error" in result: ...
• For pagination, loop until no more nextPageToken/cursor

Available in sandbox:

• call_tool(server_id, tool_name, **kwargs) — sequential
• async_call_tool(server_id, tool_name, **kwargs) — for asyncio.gather()
• call_skill(skill_id, inputs_dict) / async_call_skill(...) — call skills
• Modules: asyncio, json, datetime, math, re, collections, itertools, functools, operator, decimal, uuid, base64, hashlib
• No network, filesystem, or subprocess access
• No augmented assignment on subscripts: use d[k] = d[k] + 1, NOT d[k] += 1

---

3. Write Operation Confirmation

Write/delete operations return an audit response instead of executing. To proceed:

1. Show the operation summary to the user and wait for explicit approval

2. Get a confirmation token (expires in 60s):

   # POST /tools/confirm
   {"server_id": "SERVER_ID", "tool_name": "TOOL_NAME"}
   

3. Re-send with the token:

   # POST /tools/execute
   {"server_id": "...", "tool_name": "...", "tool_args": {...}, "confirmed": true, "confirmation_token": "TOKEN"}
   

Never call confirm without user's typed approval ("yes", "confirm", "proceed").

---

4. Skills

Skills are pre-built workflow patterns in search results with type: "skill". Prefer skills over assembling individual tools.

Executable skills

Marked executable: true. Run step-by-step:

# POST /tools/execute
{"tool_name": "SKILL_ID", "tool_args": {"step_id": "FIRST_STEP", "inputs": {...}}}

Each step returns outputs and next. If next is not null, read next.reasoning, fill placeholders, make the next call.

Guidance skills

For skills without executable: true, describe to get the pattern:

# POST /tools/describe
{"tools": [{"tool_name": "SKILL_NAME"}]}

Returns tools_involved, all_servers_connected, disconnected_servers, and step-by-step content. If all_servers_connected is false, use help(action="auth_helper") first.

---

5. Error Recovery

If a tool call fails, debug and retry — do not report failure immediately.

Error	Action
Schema/parameter error	Re-read inputSchema, fix names and types, retry
404 / "not found"	Wrong ID or tool; search for correct ID
Server not connected / 401	Call help(action="auth_helper", server_id="...")
Empty results	Try fuzzy variations, broader date ranges
Same error twice	Try different approach (different tool/parameters)
Workflow fails twice	Fall back to sequential execute calls

Only report failure after at least three different approaches have been tried.

---

Guardrails

• Start with list_servers or search to discover what's connected
• Always have inputSchema before executing (from search or describe)
• Match parameter names and types exactly
• Never fabricate data — only present actual responses
• Never execute writes without explicit user approval
• Prefer workflows for multi-step operations
• Prefer skills over assembling individual tools
• Pass session_id and user_intent on calls for tracing (API generates one if omitted)