What Is MCP? How OceanSkill Connects AI Agents to Skills

What is MCP?

Model Context Protocol, usually shortened to MCP, is a standard protocol that lets AI applications discover and call tools exposed by an external system. Instead of teaching every client a custom API, MCP provides a consistent way to initialize a connection, inspect available tools, send validated arguments, and receive structured results.

A connection layer between agents and real capabilities

A language model cannot independently read private storage, retrieve protected files, or execute a product workflow. MCP creates a clear boundary: the client orchestrates the conversation while the server publishes allowed actions. The agent sees tool names, descriptions, and input schemas, but the server retains authority over access.

Why does a shared protocol matter?

When Codex, Claude Code, Cursor, and other compatible clients understand the same protocol, developers do not need to rebuild an integration for every tool. One MCP server can serve multiple clients while maintaining consistent authentication, rate limits, ownership checks, and usage accounting.

How does OceanSkill use MCP?

OceanSkill uses MCP as the delivery gateway between its skill marketplace and AI agents. The marketplace exposes public metadata for evaluation, while executable assets such as SKILL.md and reference files are retrieved through MCP only after access has been verified.

1. The client authenticates with an MCP key

Every request includes an MCP key in the Authorization header. The server does not trust profile data supplied by the client. It resolves the key server-side, checks its owner and revocation state, and applies rate limits before a tool can run.

2. The agent discovers tools and metadata

After initialize, the client calls tools/list to receive the server capabilities. OceanSkill exposes tools for skill search, enabled-skill discovery, usage summaries, collection management, and protected content retrieval. Metadata-only operations never expose the underlying SKILL.md.

3. Access is checked against the user's library

For a public skill, the user must add and enable it in their library before retrieving content. For a private skill, the server verifies the owner. The selected release must be the current_version, have a passed scan, and resolve to exactly one current version record.

4. A credit is reserved before Storage is read

When get_skill_md or get_skill_reference begins, OceanSkill reserves one credit using a requestId. If no credits remain, the server returns a clear error without downloading the file. Reservation also prevents concurrent requests from spending the same final credit.

5. Content is downloaded and hash verified

SKILL.md is downloaded from private Storage using the current version's pinned path. The server validates size, UTF-8 encoding, and the SHA-256 hash captured at publish time. Reference files have their own size and content-hash checks, and SKILL.md is explicitly blocked from get_skill_reference to prevent billing bypass.

6. Only successful requests consume credit

After download and verification succeed, the reservation is finalized and one credit is recorded. If Storage fails, a hash differs, or processing cannot finish, the reservation is released and the user is not charged. The same requestId can replay the same scoped call for 10 minutes without another charge; reusing it for another tool, skill, version, or reference is rejected.

Two retrieval tools for two different needs

get_skill_md retrieves the primary instructions

get_skill_md returns the current SKILL.md together with its hash, size, and the references available for optional retrieval. It is the starting point when an agent needs to understand a skill workflow. Each successful new request costs one credit.

get_skill_reference retrieves optional supporting files

get_skill_reference accepts one exact referenceKey and returns UTF-8 or base64 content depending on the file type. It is designed for templates, scripts, examples, and assets that the agent may not need initially. Each successful reference retrieval costs one separate credit.

How does MCP work with collections?

OceanSkill can list platform and private collections, add a platform collection to the user's library, and create, update, or delete user-owned collections.

Sequential execution keeps outcomes controllable

When a private collection is executed, the server retrieves SKILL.md sequentially for up to 10 skills. Every successful retrieval uses the same reserve, verify, and finalize process, and execution stops at the first failure. This makes cost explicit and avoids an uncontrolled burst of parallel requests.

The security boundary of OceanSkill MCP

Public metadata, protected executable content

The marketplace needs only titles, descriptions, categories, and compatibility information. Executable content remains in private Storage behind the server. The service-role key never reaches the frontend, and an agent cannot supply an arbitrary path to read files outside a published version.

Publish-time hash pinning instead of first-read trust

SKILL.md and reference hashes are recorded during publication. Every retrieval compares the actual bytes with the stored hash. If a Storage object changes outside the publication workflow, MCP rejects it rather than silently trusting the new content.

Connect to OceanSkill MCP

Create an MCP key in the Dashboard, add a skill or collection to your library, and configure the server URL and Authorization header in your client. See the complete example at the OceanSkill MCP connection guide.

Start small before composing a workflow

Test one skill with an outcome you can verify. Once initialize, tools/list, and get_skill_md work reliably, add references or multi-step collections. This approach makes connection, permission, credit, and content failures much easier to isolate.