TinyFish + OpenCode: Free Web Search for AI Agents

Your local model can write a clean function and still hand you an install command for a package that changed months ago. It sounds equally sure either way. Training data has a cutoff, and live web access gives the model a way to check what is true today.

TinyFish adds that check to OpenCode Desktop through MCP. Its Search tool finds current pages and returns titles, snippets, and URLs. Its Fetch tool takes a URL you already have and returns clean page content instead of raw HTML.

Search and Fetch cost 0 credits on every TinyFish plan. Rate limits still apply, and they are generous enough for normal research.

This guide covers the OpenCode desktop app. Windows paths come first, with macOS and Linux right after. Your model can be a cloud model, an LM Studio model, or an Ollama model, as long as it supports tool calling. Yoooooooooooooooooooooooooooooooooo

What TinyFish adds to OpenCode

Hello

TinyFish exposes 4 web tools through one MCP connection, and they are not interchangeable.

OpenCode registers MCP tools with the server name in front, so the tool calls in your session will read tinyfish_search and tinyfish_fetch_content rather than the product names. Worth knowing before you go looking for a tool called Fetch.

For normal research or coding work, Search and Fetch are usually enough. A good pattern looks like this:

1. Search for the best current sources.
2. Keep the 2 to 4 most useful URLs.
3. Fetch those pages.
4. Ask the model to compare the evidence.
5. Make code changes only after the evidence is clear.

That uses far less context than fetching every result, and it gives a small local model a much easier job.

Before you start

You need:

• OpenCode Desktop installed and opening normally.
• A working model selected inside OpenCode.
• A free TinyFish account. Sign-up takes no card, and new accounts start with 500 credits for the paid tools.
• A text editor such as Notepad, VS Code, or Notepad++.
• A backup copy of your OpenCode config.
• A default browser where you can sign in to TinyFish.

Running a local model? Start the LM Studio or Ollama server before you test the MCP connection.

Dependable tool calling matters more here than raw model quality. OpenCode's own provider guide warns that some local models handle tool calls far better than others.

Step 1: Check whether OpenCode web search already works

Open a new OpenCode session and try this:

If the model calls websearch and gives you the official OpenCode page, you already have basic live search.

OPENCODE_ENABLE_EXA=1 opencode

You may still prefer TinyFish when:

• Your local model ignores the built-in tool.
• You want TinyFish Fetch for cleaner page retrieval.
• You use TinyFish in other MCP-compatible tools and want one consistent workflow.
• You want your web research tools kept separate from OpenCode's built-in ones.
• You need the structured Search and Fetch behavior TinyFish returns.

Avoid enabling several overlapping search MCPs without a reason. Every MCP server adds its tool descriptions to the model's context, and OpenCode's docs flag that this piles up quickly.

Step 2: Create your TinyFish account

Go to agent.tinyfish.ai and create an account. No credit card is required, and Search and Fetch work straight away.

You do not need to create an API key for this MCP setup. TinyFish's REST API uses API keys, while its MCP endpoint uses OAuth 2.1. The browser login connects OpenCode to your TinyFish account and caches the authorization for later sessions.

Search and Fetch sit at 0 credits on every plan. What changes between plans is how fast you can call them.

Going over the limit returns a 429 error rather than an unexpected charge. For one developer doing manual research, the free tier is plenty.

Step 3: Open the correct OpenCode config file

Windows

macOS and Linux

Open:

~/.config/opencode/opencode.jsonc

Some older installations keep it here instead:

~/.local/share/opencode/opencode.jsonc

Global or project-only setup?

The global config makes TinyFish available across all your OpenCode projects.

You can also create an opencode.json file in one project's root folder, which keeps TinyFish limited to that project. OpenCode merges its config sources, so project settings override conflicting global keys without deleting unrelated values.

For a first setup, the global config is simpler.

Step 4: Back up the file before editing

Copy opencode.jsonc and rename the copy to something like:

opencode-backup-before-tinyfish.jsonc

Do not delete your existing config and replace it blindly. Your current file may already contain:

• Your LM Studio or Ollama provider.
• A default model.
• Other MCP servers.
• Permissions.
• Plugins.
• Compaction settings.
• Project instructions.

The safe job is to add the tinyfish entry inside the configuration you already have.

Step 5: Add the TinyFish MCP configuration

If your config is empty or only contains the schema line, use this:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tinyfish": {
      "type": "remote",
      "url": "https://agent.tinyfish.ai/mcp",
      "enabled": true
    }
  }
}

OpenCode requires every remote MCP entry to include type: "remote" and the server URL. The current TinyFish MCP endpoint is https://agent.tinyfish.ai/mcp.

If you already have an mcp object, add TinyFish inside it:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "your-existing-provider/your-existing-model",
  "mcp": {
    "your-existing-server": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "enabled": true
    },
    "tinyfish": {
      "type": "remote",
      "url": "https://agent.tinyfish.ai/mcp",
      "enabled": true
    }
  }
}

Keep your real provider, model, plugin, permission, and instruction settings. The example only shows where the TinyFish entry belongs.

Common JSON mistakes

Watch for:

• A missing comma before "tinyfish".
• Two separate top-level "mcp" objects.
• Smart quotes copied from a formatted document.
• A closing brace in the wrong place.
• Deleting an existing provider block.
• Saving the file as opencode.jsonc.txt.

JSONC allows comments and trailing commas. The object structure still has to be valid.

Step 6: Restart OpenCode Desktop

Save the config, close the editor, and launch OpenCode Desktop again.

A full restart matters because OpenCode loads MCP configuration when it starts. If the app was only minimized to the system tray, quit it completely and reopen it.

Open a fresh project session after the restart.

Step 7: Complete TinyFish OAuth authentication

Use a prompt that clearly names the TinyFish tool:

On the first TinyFish call, OpenCode should detect that the remote MCP needs authorization and open your browser. Then:

OpenCode handles OAuth for compatible remote MCP servers on its own. It detects the 401 response, registers itself with the server automatically where that is supported, and stores the tokens in ~/.local/share/opencode/mcp-auth.json for later sessions.

If the browser never opens, you can start the flow by hand:

opencode mcp auth tinyfish

Step 8: Test Search and Fetch separately

Testing one tool at a time makes problems much easier to spot.

Search test

A successful result shows a TinyFish Search tool call and returns several URLs.

Fetch test

Choose one URL from the Search result and use:

A successful result shows the Fetch tool reading that specific page.

Search is for discovery. Fetch is for retrieval. TinyFish's API guide draws the same line, and so does OpenCode's own tools page.

Step 9: Prepare a local model for web research

A model can be strong at chat and code generation and still be poor at tool calling. TinyFish cannot fix that half.

LM Studio

Confirm that:

• The model is loaded.
• The local server is running.
• OpenCode points to http://127.0.0.1:1234/v1.
• The model supports tool or function calling.

When tool calls keep failing, load a model with stronger tool support. OpenCode's docs point to Qwen-Coder or DeepSeek-Coder variants as reliable choices.

Ollama

Confirm that:

• Ollama is running.
• OpenCode points to http://localhost:11434/v1.
• The selected model supports tools.
• The context window is large enough for the task.

These are the current default local endpoints shown in OpenCode's provider documentation. Ollama can also configure itself for OpenCode through its own integration docs, which saves you writing the provider block by hand.

How much context do you need?

There is no universal minimum of 64,000 tokens. A practical starting point:

• 16K to 32K: simple searches, 1 or 2 fetched pages, short coding questions.
• 64K: safer for multi-source research, long documentation, and codebase comparison.
• Above 64K: useful only when your model and hardware can handle it without becoming painfully slow.

OpenCode's Ollama guidance suggests raising num_ctx and starting around 16K to 32K when tool calls are failing. More context helps, and it also increases RAM or VRAM use and slows local generation.

Context size is a poor substitute for a controlled workflow. Search first, fetch only the best pages, and ask for a focused answer.

The best TinyFish workflow for coding research

The cleanest workflow is a small research funnel.

1. Define the exact question

Weak: Search the web and tell me about React.

Better: Find the current official React documentation for server components and identify the API changes that affect this project.

2. Search official sources first

Ask TinyFish Search to prioritize:

• Official documentation.
• Official release notes.
• Maintainer repositories.
• Standards pages.
• Original research.

3. Fetch only the useful pages

Do not fetch 10 pages because 10 appeared in the results.

Fetch 2 to 4 strong sources. A small model compares a few clean pages far more reliably than a huge pile of mixed-quality text. TinyFish Fetch accepts up to 10 URLs in a single request, which makes over-fetching easy, so set the limit yourself.

4. Compare the web evidence with your project

Ask the model to inspect the relevant files after it has read the current docs.

5. Require a plan before edits

This keeps a weak search result from turning into an immediate code change.

6. Verify the final change

Ask the model to state:

• Which source supported the change.
• Which files were edited.
• What assumptions remain.
• What test should confirm the result.

Copy-paste prompt for safe web research in OpenCode

Use this once TinyFish Search and Fetch are working.

This prompt is deliberately strict. It keeps the local model focused, limits how much web content lands in the session, and lowers the chance that one weak result turns into a code change.

Optional: Install the TinyFish skill

TinyFish publishes an official use-tinyfish skill that teaches coding agents when to choose Search, Fetch, Agent, or Browser. The cookbook lists OpenCode among the supported coding agents.

The one-line installer:

npx skills add github.com/tinyfish-io/tinyfish-cookbook --skill use-tinyfish

For a project-local manual install, the final file belongs here:

.opencode/skills/use-tinyfish/SKILL.md

OpenCode discovers project skills from .opencode/skills/<name>/SKILL.md and global ones from ~/.config/opencode/skills/<name>/SKILL.md. A stray skill.md in your project root does nothing, and the filename has to be in capitals.

The skill is optional. Skip it when your model already picks the correct TinyFish tools from clear prompts. Small models often benefit from the extra guidance, and every added instruction also spends context.

How to keep token use under control

Web access fills a local model's context quickly, and the search itself is rarely the only problem.

Your context window is one desk. Tool descriptions, search results, fetched pages, your project files, and the model's answer all have to fit on it at the same time.

Use these rules:

1. Search before fetching.
2. Fetch only 2 to 4 pages.
3. Prefer official sources over 10 secondary summaries.
4. Ask for a structured answer.
5. Use one research question per session.
6. Start a new session before implementation if the research session became large.
7. Disable MCP servers you are not using.
8. Avoid asking a small model to research, inspect an entire repository, edit files, and write documentation in one turn.
9. Keep long generic skill files out of projects that do not need them.
10. Tell the model to use Search and Fetch only when you want to avoid the paid TinyFish tools.

Rule 7 is easy to miss, and OpenCode gives you a clean way to do it. Disable a server's tools globally with a glob, then switch them back on for the one agent that needs them:

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "tinyfish*": false
  },
  "agent": {
    "research": {
      "tools": {
        "tinyfish*": true
      }
    }
  }
}

OpenCode warns that MCP tools add to context, and that heavy servers can push a session past the limit on their own. A bigger context window gives you room. A cleaner workflow usually gives you a better answer.

Does web search stop AI hallucinations?

No.

Live web access lowers the chance of an answer being stale or invented from memory, and it gives the model evidence it can cite. The model can still:

• Choose a weak source.
• Misread a page.
• Mix facts from different versions.
• Treat a search snippet as full evidence.
• Ignore a conflicting source.
• Produce a citation that does not support the sentence.

For important coding, security, legal, medical, or financial decisions, open the source yourself and verify the critical claim.

Search for the source, fetch the actual page, show the URL, separate fact from inference, and flag uncertainty.

Troubleshooting

TinyFish does not appear or respond

Check:

• The config file path is correct.
• The file is named opencode.jsonc or opencode.json.
• The TinyFish object sits inside "mcp".
• The server type is "remote".
• The URL is exactly https://agent.tinyfish.ai/mcp.
• OpenCode was fully restarted.
• The JSON braces and commas are valid.

This command lists every configured MCP server with its auth status, which settles most of the guesswork:

opencode mcp list

Restore your backup if OpenCode stops opening after the edit.

The browser login does not open

Start a new session and ask explicitly for TinyFish Search. Then check that your default browser can reach TinyFish and that you are signed in there, because the OAuth redirect lands in whichever browser your system treats as default.

If authentication still fails, run the diagnostics rather than rewriting the config:

opencode mcp auth list
opencode mcp debug tinyfish

The debug command shows the auth status, tests HTTP connectivity, and attempts the OAuth discovery flow.

The model answers without calling TinyFish

Say this:

If it still refuses, switch to a model with stronger tool-calling support. This is common with small local models.

The model calls TinyFish Agent or Browser

Stop the run if you only intended to use the free tools, then use explicit wording:

Agent costs 1 credit per run step and Browser costs 1 credit per 4 browser-minutes, while Search and Fetch stay at 0. Prompts are one layer of protection, and permissions are a firmer one:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "tinyfish_run_web_automation": "ask",
    "tinyfish_create_browser_session": "ask"
  }
}

Now the paid tools need your approval before they run.

You get a 429 error

You reached the Search or Fetch rate limit. Wait for the limit window to reset, reduce repeated calls, and try again.

The free-tier limits are high enough for normal manual research. A looping agent can hit them in under a minute.

The context window fills too quickly

Reduce the number of fetched pages. Ask for shorter extracts. Start a new session after the research phase.

A 64K window helps with multi-source work, and it will not rescue an agent that fetches everything it sees.

A 15-minute setup plan

Minutes 0 to 3

• Create or sign in to TinyFish.
• Close OpenCode.
• Find and back up opencode.jsonc.

Minutes 3 to 7

• Add the TinyFish remote MCP object.
• Validate the braces and commas.
• Save the file.

Minutes 7 to 10

• Restart OpenCode.
• Open a fresh session.
• Trigger TinyFish Search.
• Complete browser authentication.

Minutes 10 to 15

• Run the Search test.
• Fetch one official page.
• Try the safe research prompt on one real coding question.

Do not install the optional skill until the basic MCP connection works. That keeps setup problems separate from instruction problems.

Your next step

Back up your OpenCode config, add the TinyFish MCP entry, and run the Search-only test prompt.

Once it returns current official sources, fetch one of those pages and compare the result with your model's memory-only answer. That small test shows you whether TinyFish improves your actual OpenCode workflow before you add more skills, tools, or automation.