OceanSkill documentation

From marketplace to MCP in one clear workflow

Connect an agent client, manage skills and collections, understand credits and requestId, and troubleshoot MCP calls without exposing your key.

Quickstart

Connect OceanSkill in four steps

Your dashboard is the control plane; your MCP-compatible client is where skills are used.

Create your account

Create an MCP key

Create a dedicated key in Dashboard → MCP keys. Copy it immediately because the full key is shown once.

Configure your client

Add the Supabase Edge Function endpoint and send the key in the Authorization header.

Verify the connection

Ask your agent to list OceanSkill tools, search the catalog, or show your available skills.

Configuration

Add the MCP server to your client

Use this JSON shape in Codex, Claude Code, Cursor, or another MCP client. Replace both placeholders with your project endpoint and MCP key.

mcp.json

{
  "mcpServers": {
    "oceanskill": {
      "serverUrl": "https://YOUR_PROJECT.supabase.co/functions/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_NSK_KEY"
      }
    }
  }
}

key_offKeep keys local. Never commit an nsk_ key, paste it into frontend code, or share it in screenshots.

What each value means

serverUrl points to the deployed Supabase Edge Function: /functions/v1/mcp.

Authorization uses Bearer followed by the nsk_ key created in your dashboard.

After saving, restart or reload the MCP client so it discovers the latest tools.

Daily workflow

Discover, enable, then invoke

Public pages help you evaluate skills. Your library and collections decide what your agent can use.

travel_explore

Discover

Browse categories, authors, compatibility, versions, tags, and public descriptions.

library_add_check

Enable

Add a skill or collection to your library, then enable only the skills you want exposed to your agent.

play_circle

Invoke

Ask the agent to use a named skill. OceanSkill returns the scanned current version through authenticated MCP.

Skills you own

Publish private skills and add slots when needed

Every account includes 5 private-skill slots. The dashboard identifies the signed-in user as the author, while verified content and hashes remain protected behind Storage and MCP.

Upload a skill package

Open Dashboard → My skills → Uploaded skills, enter metadata, then provide SKILL.md or a reviewed ZIP/RAR package.

Use 5 included slots

Platform skills added to your library do not count. Only private skills you publish consume these slots.

5,000 VND per extra slot

When the allowance is full, Billing opens at 5,000 VND. Choose a larger multiple to buy several slots in one payment.

Buy more skill slots

Collections

Group skills into reusable collections

Discover platform collections in the skill marketplace. They appear in the dashboard only after you add them, where three tabs separate all, platform, and user-owned collections.

storefront

Browse in the marketplace

Open a platform collection card to review its description and every included skill before adding it.

library_add

Add it explicitly

Choose Add to my collections. Until then, the platform collection remains outside your dashboard.

tab

Use three dashboard tabs

Switch between All, Platform, and Mine. Platform collections are read-only; owned collections can be created, edited, and deleted.

Usage safety

How requestId prevents duplicate charges

requestId is a per-call idempotency key for get_skill_md and get_skill_reference. Its exact-replay window lasts 10 minutes, and most MCP clients can let OceanSkill generate it automatically.

add_circle

New work, new ID

Use a new requestId for a new skill-content attempt. It may contain 1–120 characters.

replay

Retry within 10 minutes

Reuse the same requestId only for the same tool, skill, current version, and reference within 10 minutes. OceanSkill marks it replayed and charges 0 extra credits.

error

A failed attempt needs a new ID

Failed calls release their reservation and explain whether retry is allowed. Start the next attempt with a new requestId.

swap_horiz

Never reuse it across scopes

Using one requestId for another skill, version, or tool returns REQUEST_ID_CONFLICT instead of charging ambiguously.

Credit rule

Each successful new get_skill_md or get_skill_reference call costs 1 credit. OceanSkill reserves one credit before reading, finalizes the debit only after success, and releases the reservation after failure. Search, listing, collection, toggle, and usage-summary tools remain free.

Reference

Available MCP tools

These are the tools exposed by the current OceanSkill MCP server.

list_purchased_skills

List enabled public and owned private skills available to the account.

search_skills

Search available metadata without exposing protected SKILL.md content.

get_skill_md

Download the scanned current SKILL.md directly from private Storage and return available reference keys; accepts an optional requestId.

get_skill_reference

Return one mapped file from the current skill version. Text uses UTF-8 and binary content uses base64.

list_collections

List public collections and collections owned by the authenticated user.

add_collection_to_library

Add an accessible collection to the user library and enable its skills.

create_skill_collection

Create a private collection with a name, collection key, and ordered skill list.

update_skill_collection

Rename, describe, re-key, or replace the skills in a user-owned collection.

delete_skill_collection

Delete a user-owned collection. Platform collections cannot be deleted.

execute_skill_collection

Fetch SKILL.md sequentially for up to 10 skills in an owned collection; each successful fetch costs 1 credit.

toggle_skill

Enable or disable one library skill without fetching paid content.

get_usage_summary

Return the current credit balance and month-to-date MCP usage.

Troubleshooting

Understand errors before retrying

401 · INVALID_KEY

Confirm the Authorization header uses Bearer and an active nsk_ key from the same account.

402 · INSUFFICIENT_CREDITS

Open Billing to top up. The response is clear and no content credit is charged.

403 · NOT AVAILABLE

Add or enable the skill in your library and confirm that its current version is active.

409 · REQUEST/VERSION CONFLICT

Follow the returned retryable flag. Use a new requestId after failure or version change.

500 · INTERNAL_ERROR

The response includes a stable errorCode and may include requestId. Keep those values when reporting the issue; do not include your key.

Ready to connect your agent?

Create an MCP key, add your first collection, and check usage from the dashboard.

Create MCP key Open collections