How Agent Skills and MCP Tools Function Together in OpenSEO

OpenSEO uses the Model-Control Protocol (MCP) to expose SEO data APIs, while agent skills define slash commands and workflows that orchestrate when and how those tools are called.

The OpenSEO platform is architected around a clean separation between data provision and workflow orchestration. MCP tools deliver live SEO intelligence, and agent skills consume those tools to build conversational SEO workflows. This design lets any MCP-compatible AI client operate on real project data without hardcoding API logic.

What OpenSEO MCP Provides

The MCP server exposes a collection of stateless, project-scoped RPC tools for keyword research, SERP inspection, Google Search Console data, backlink lookup, and rank tracking. When an AI client connects, it receives an authentication token and base URL to access these endpoints.

Per the [web/content/docs/mcp.md](/web/content/docs/mcp.md) documentation, the MCP layer handles:

• Authentication — validates tokens and resolves project scopes
• Service routing — dispatches calls to underlying providers (DataForSEO, GSC, internal rank trackers)
• Structured responses — returns typed JSON payloads that skills can parse

MCP tools are intentionally stateless and project-scoped, making them portable across any AI platform that supports the protocol.

What Agent Skills Provide

Agent skills are declarative workflow files (typically SKILL.md) that live in .agents/skills/ or the agent's local skills directory. Each skill defines:

• A slash command (e.g., /keyword-research)
• Parameter schemas for user inputs
• MCP tool invocations with mapped arguments
• Response formatting logic to translate JSON into natural language

Skills act as the consumer layer — they determine when to call a specific MCP method, how to structure the request, and how to present results to the user.

The Integration Flow

The following sequence demonstrates how MCP tools and agent skills function together in practice:

1. Connect MCP — The user runs npx mcp login to link their AI client to OpenSEO's MCP server, obtaining a token and endpoint.

2. Install skills — The user adds skill definitions via npx skills add every-app/open-seo or manual installation of skill files.

3. Trigger workflow — Invoking /keyword-research "organic coffee beans" causes the agent to:

   • Parse the skill definition
   • Format parameters (query, location, language)
   • POST to the MCP tool endpoint

4. Execute tool — The MCP server validates, resolves project context, queries DataForSEO, and returns structured keyword data.

5. Handle response — The skill parses the JSON payload, generates a formatted answer, and optionally writes results back to the OpenSEO project UI.

# Connect MCP once per account

npx mcp login

# Install OpenSEO skills for your AI client

npx skills add every-app/open-seo --skill 'keyword-research,competitor-analysis'

# Use inside Claude, Codex, or Cursor

/keyword-research "organic coffee beans" --location us --language en

Under the hood, the skill translates the slash command into an MCP request similar to:

POST https://mcp.openseo.so/v1/research_keywords
{
  "projectId": "proj_123",
  "query": "organic coffee beans",
  "location": "us",
  "language": "en",
  "includeClickstreamData": true
}

Key Architectural Files

The source and specification files define this separation explicitly:

File	Role in MCP-Skill Synergy
[web/content/docs/mcp.md](/web/content/docs/mcp.md)	Documents available MCP tools and connection flow
[web/content/docs/skills/setup.md](/web/content/docs/skills/setup.md)	Installation guide for skill files post-MCP connection
[web/content/docs/skills/index.md](/web/content/docs/skills/index.md)	Reference for all slash commands and their MCP mappings
[specs/0006-onboarding-agent-implementation.md](/specs/0006-onboarding-agent-implementation.md)	Defines the get_project_context MCP tool used by the agents package
[specs/0005-onboarding-agent.md](/specs/0005-onboarding-agent.md)	Specifies the "Project Context" artifact structure exposed over MCP
.agents/skills/	Repository folder containing SKILL.md definitions (referenced in docs, hosted separately)

Design Benefits

This architecture enables several operational advantages:

• Portability — Skills work across Claude, Codex, Cursor, or any future MCP client without modification
• Maintainability — API changes propagate through MCP layer; skills remain stable
• Extensibility — New SEO capabilities require only a new MCP tool plus skill definition
• Security — Project scoping and authentication reside in MCP, not skill code

Summary

• MCP tools expose SEO data as stateless, authenticated HTTP endpoints
• Agent skills define conversational workflows that invoke MCP tools via slash commands
• The integration follows a three-step pattern: connect MCP → install skills → trigger workflows
• Source specifications in specs/0005-onboarding-agent.md and specs/0006-onboarding-agent-implementation.md formalize the get_project_context contract between layers

Frequently Asked Questions

What is the Model-Control Protocol (MCP) in OpenSEO?

MCP is a standardized protocol that exposes OpenSEO's SEO data services as callable tools any compatible AI client can invoke. It handles authentication, project scoping, and structured response formatting so AI agents don't need direct API credentials.

How do I add OpenSEO skills to my AI agent?

Use the npx skills add every-app/open-seo command to install skill definitions, or manually copy SKILL.md files into your agent's skills directory. Ensure you've completed npx mcp login first to establish the data connection.

Can I use OpenSEO skills without the MCP server?

No. Skills depend on MCP tools to fetch live data. Without the MCP connection, slash commands will fail when attempting to query keyword metrics, SERP data, or other SEO intelligence.

Where are the skill files stored in the repository?

Skill definitions reside in the .agents/skills/ folder, though this directory is typically distributed separately from the main source. Setup documentation in [web/content/docs/skills/setup.md](/web/content/docs/skills/setup.md) covers installation methods.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}