---
name: mcp-forge-conventions
description: How to call MCP tools from within mcp-forge execute_python scripts, including tool naming and injection syntax
---

# mcp-forge Conventions

## Tool naming

mcp-forge injects tools using their **bare function name**, not the namespaced name visible to the agent.

| Agent-side name | mcp-forge `mcp_tools` value | In-script call |
|---|---|---|
| `searxng_search` | `"search"` | `search(...)` |
| `searxng_fetch` | `"fetch"` | `fetch(...)` |
| `rag-mcp_browse_documents` | `"browse_documents"` | `browse_documents(...)` |
| `rag-mcp_search_records` | `"search_records"` | `search_records(...)` |

The pattern: strip any server prefix (e.g. `searxng_`, `rag-mcp_`) and use only the function name.

## Calling injected tools — keyword-only arguments

Injected tool functions are **keyword-only wrappers**. Always pass arguments by name:

```python
# correct
results = search(query="foo", language="en")
page = fetch(url="https://example.com", max_chars=2000)

# wrong — positional args raise TypeError
results = search("foo")
```

## Injection syntax

Pass a JSON array of bare tool names to `mcp_tools`:

```python
mcp-forge_execute_python(
    code='results = search(query="foo"); print(results)',
    mcp_tools=["search", "fetch"]
)
```

## Listing all available tools

Use the agent-side `mcp-forge_list_injectable_tools` tool to get the full catalogue before writing scripts:

```
mcp-forge_list_injectable_tools(include_schemas=false)
```

Returns each tool's `tool_name` (injected name), `qualified_name` (`provider.tool`), and provider metadata (name, transport, url). Only tools whose providers are registered in mcp-forge's own config appear here — tools available to the OpenCode agent from other MCP servers (e.g. GitHub) are NOT automatically available inside mcp-forge.

## Verifying a single tool name

To confirm a specific tool name resolves before using it, pass it in `mcp_tools` and check the `available_tools` list in the response. Only successfully resolved tools appear there.

```python
mcp-forge_execute_python(
    code='print("ok")',
    mcp_tools=["search"]
)
# response includes: "available_tools": ["search"]
# if the name is wrong, the whole call errors with "Tool '<name>' not found"
```

## Return values

Injected tools return Python objects (lists, dicts). Handle both a direct value and a dict wrapper:

```python
data = search(query="foo")
records = data.get("result", []) if isinstance(data, dict) else data
```

## Combining searxng + mcp-forge

```python
mcp-forge_execute_python(
    code='''
results = search(query="uv python", language="en")
top = results[0]
page = fetch(url=top["url"], max_chars=2000)
print(page["content"])
''',
    mcp_tools=["search", "fetch"]
)
```