Setup & Authentication

Security Important!

Your API key grants access to your Yoku account. Keep it secure:

• Never commit it to version control
• Don't share it publicly
• Use environment variables or secure credential storage
• Create separate keys for different environments ::

Authentication Format

All requests to the MCP server must include your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Your API key will look like this:

yoku_live_1234567890abcdef1234567890abcdef

Rate Limits & Quotas

Your MCP server access is governed by your subscription plan:

What Happens When You Hit the Limit?

When you reach your monthly quota:

• The server returns an error with code -32603
• The response includes a Retry-After header with seconds until the next month
• Your AI client will receive a clear error message

Example error response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "API request limit reached for your current plan."
  },
  "id": null
}

Session Management

The MCP server uses session-based connections to maintain state across multiple requests:

1. First Request - Client sends an initialize request without a session ID
2. Server Response - Returns an Mcp-Session-Id header
3. Subsequent Requests - Client includes the session ID in all future requests
4. Session Timeout - Sessions expire after 10 minutes of inactivity

This is handled automatically by MCP clients - you don't need to manage sessions manually.

Testing Your Connection

Using cURL

You can test the MCP server directly using cURL:

curl -X POST https://mcp.yoku.app \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    },
    "id": 1
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "logging": {},
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "yoku-mcp",
      "version": "1.0.0"
    }
  },
  "id": 1
}

Listing Available Tools

After initialization, you can list available tools:

curl -X POST https://mcp.yoku.app \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }'

Troubleshooting

"Unauthorized" Error

Problem: Receiving 401 Unauthorized errors

Solutions:

• Verify your API key is correct
• Check that the Authorization header is properly formatted
• Ensure your API key hasn't been revoked
• Confirm you're using Bearer prefix before the key

"Session not found" Error

Problem: Receiving session not found errors

Solutions:

• Your session may have expired (10-minute timeout)
• Send a new initialize request to create a fresh session
• Ensure your client is sending the Mcp-Session-Id header correctly

"API request limit reached" Error

Problem: Hit your monthly quota

Solutions:

• Wait until the next month (check Retry-After header)
• Upgrade your plan in billing settings
• Optimize your tool usage to reduce request count

Connection Timeout

Problem: Requests are timing out

Solutions:

• Check your network connection
• Verify the server URL is correct: https://mcp.yoku.app
• Ensure you're not behind a firewall blocking HTTPS requests
• Try with a longer timeout setting in your client

Environment Variables

For security, store your API key in environment variables:

For Unix/Linux/macOS:

export YOKU_API_KEY="yoku_live_your_key_here"

For Windows (PowerShell):

$env:YOKU_API_KEY="yoku_live_your_key_here"

In your application:

const apiKey = process.env.YOKU_API_KEY;

Next Steps

Now that you understand authentication and setup, configure your specific MCP client:

• Cursor Integration - Configure Cursor for AI-assisted development
• Jan Integration - Set up Jan AI with Yoku's MCP server
• Tools Reference - Explore available tools and their parameters

Need Help?

If you encounter any issues:

1. Check the troubleshooting section above
2. Review your API key in dashboard settings
3. Contact support at contact@yoku.app