Research keywords through OpenSEO MCP

OpenSEO’s MCP server lets a coding agent research keywords and save the useful ones in a project. You can give the agent the business context, inspect the evidence it returns, and decide which ideas deserve more work.

We’ll connect OpenCode, check the existing project, then prepare one small research request. The setup doesn’t require making a paid query. Fresh research comes later, after you approve its scope and cost.

My OpenSEO guide explains the application and its data providers. Here we’ll follow the actual tool workflow for a hypothetical reading-club app.

Connect the hosted server

You need an OpenSEO account and an existing project. OpenSEO’s MCP setup guide gives this hosted endpoint:

https://app.openseo.so/mcp

In the directory where you use OpenCode, add it with the current CLI:

opencode mcp add openseo --url https://app.openseo.so/mcp
opencode mcp list

If it needs authentication, run:

opencode mcp auth openseo

Complete the OpenSEO login and inspect the access you’re granting. You can also open OpenCode, enter /mcps, and select the server to authenticate. These commands follow OpenCode’s current MCP documentation.

If you prefer a configuration file, the equivalent server belongs in opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "openseo": {
        "type": "remote",
        "url": "https://app.openseo.so/mcp"
      }
    }
  }
}

Current OpenCode uses mcp.servers. Older examples place named servers directly under mcp, which is a different configuration shape.

OAuth keeps the access credential out of this project file. OpenSEO also supports personal API keys for clients that need them. Use the client’s environment-variable substitution for that route, rather than saving the key in JSON or pasting it into a prompt. A DataForSEO credential belongs in the OpenSEO installation’s provider setup, rather than the MCP connection.

Read the project before researching

Start with this request:

Use OpenSEO. Call list_projects and show me the available project names,
organizations, domains, locationCode, and languageCode.
Do not create or update anything and do not run paid research.

Choose the intended project from the returned list. The tools use its actual id as projectId; don’t ask the agent to invent an ID from the project name.

Then ask it to call get_project_context and list_saved_keywords for that project. These provide existing business context and saved ideas, without buying fresh market data.

The project-list tool returns default market settings. Check them carefully. An English-language app aimed at the United States needs different research settings from an Italian-language local club.

For the example below, the intended country is the United States (2840) and the language is English (en). Confirm those settings in the project before proceeding. Keep them with the results so later comparisons use the same market.

Prepare one paid operation

OpenSEO’s research_keywords tool accepts one to five seeds. Each seed is researched independently. Its supported resultLimit values are 150, 300, and 500.

A request for a ten-keyword shortlist can therefore retrieve up to 150 results and select ten afterward. Setting resultLimit: 10 doesn’t match the current schema.

Ask the agent to prepare the request before executing it:

For the selected reading-club project, prepare one research_keywords call.
Use one seed: "book club app".
Set locationCode to 2840 and languageCode to "en" on that seed.
Set resultLimit to 150, includeClickstreamData to false,
and groupKeywords to false. Do not add a local-area locationName.
Show the intended request and current cost information, including possible
fallback costs. Wait for my approval before running it.

Fresh research consumes provider usage or hosted credits. The tool can perform fallback work internally, so one MCP call doesn’t necessarily mean one upstream provider request. Clickstream refinement can also change the cost.

A prompt limits what you’re asking the agent to do. Enforce a financial ceiling through the provider or application account controls where available. If you can’t establish an acceptable bound, leave the request unexecuted.

After checking the current terms, you can approve that single prepared call. Keep any follow-up expansion separate. I haven’t executed a paid lookup for this tutorial, so there are no invented volume or difficulty numbers to copy.

Read the returned evidence

The response can contain a successful result or an error for each seed. Have the agent show the source, market, and whether fallback work occurred before interpreting the keyword rows.

Ask for a shortlist based on the app’s actual purpose. For a reading-club organizer, a phrase about scheduling group discussions may fit better than a high-volume search for book summaries.

Treat missing metrics as missing. A null difficulty value doesn’t mean zero difficulty. Keep the provider’s estimates separate from evidence about your own website, such as Search Console clicks.

The model’s explanation should help you judge relevance. It shouldn’t silently fill gaps in the data.

Save the keywords you choose

Researching and saving are separate operations. After reviewing the shortlist, name the phrases you want retained and ask the agent to call save_keywords.

Have it use the same projectId, locationCode, and languageCode. If it saves metrics, it should copy the returned fields for the matching keyword. Don’t let it substitute estimates from memory.

Saving existing research doesn’t make a DataForSEO request. Tags can change shared organization in the project, so leave them out unless you’ve chosen how to apply them.

Finally, call list_saved_keywords again and check the rows in OpenSEO’s interface. You should be able to find the selected phrases in the intended market without rerunning paid research. That gives the next session an existing record to read before it proposes another lookup.

Want me to talk about your product? You can sponsor this site.