🚀 MCP Server Setup Guide

Connect Oshaani MCP to Cursor, Claude, and other agents — user key for agent management, agent key for conversations

📑 Table of Contents

1. Overview

The Oshaani MCP (Model Context Protocol) Server exposes two HTTP endpoints on https://mcp.oshaani.com. Use a user API key to manage agents, or an agent API key to run conversations, webhooks, and file operations.

🌐 Base URL: https://mcp.oshaani.com
Health check: GET /health (no auth)

User MCP Profile key

POST /mcp

Create and manage agents from your Oshaani account.

list_models create_agent get_agent list_agents update_agent delete_agent

Agent MCP Agent key

POST /agent/mcp

Chat, webhooks, and files for a published agent.

create_conversation continue_conversation agent_webhook get_answer find_conversation upload_file download_file create_upload_url get_download_url

Endpoint summary

Path API key Tools
/mcp User key (profile) Agent CRUD & model listing
/agent/mcp Agent key (dashboard) Conversations, webhooks, files

Async conversation workflow

create_conversation or agent_webhook → Receive request_id + conversation_id → Poll get_answer until completed → continue_conversation for follow-ups
Tip: Register both MCP servers in Cursor if you want agent management and live conversations in the same workspace. Each uses a different URL and API key type.

2. API Keys (User vs Agent)

Oshaani uses two key types. Using the wrong key on an endpoint returns 401 Unauthorized with a message telling you which endpoint to use instead.

User API key for /mcp

  1. Log in at oshaani.com
  2. Open Profile → API Keys
  3. Generate or copy your user API key

Use for: creating agents, listing models, updating agent settings.

Agent API key for /agent/mcp

  1. Open your agent in the Oshaani dashboard
  2. Ensure the agent is published
  3. Copy the agent API key from the agent settings / test page

Use for: chat, webhooks, file upload/download for that agent only.

⚠️ Security: Treat both keys like passwords. Never commit them to git or share them publicly. Regenerate immediately if exposed.

3. Adding to Cursor Recommended

Cursor is a popular AI-powered code editor that supports MCP servers. Here's how to add the Oshaani MCP server:

1 Open Cursor Settings

Open Cursor and go to Settings → Features → MCP Servers or edit the MCP configuration file directly.

2 Edit MCP Configuration

Open or create the MCP configuration file. The location depends on your OS:

  • macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
  • Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json
  • Linux: ~/.config/Cursor/User/globalStorage/mcp.json
3 Add server configuration

Add one or both MCP servers. Most users want agent conversation tools; add the user server if you also manage agents from Cursor.

{
  "mcpServers": {
    "oshaani-agent-management": {
      "url": "https://mcp.oshaani.com/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_USER_API_KEY_HERE"
      }
    },
    "oshaani-agent-conversation": {
      "url": "https://mcp.oshaani.com/agent/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_AGENT_API_KEY_HERE"
      }
    }
  }
}
4 Replace API keys

YOUR_USER_API_KEY_HERE — from Profile → API Keys
YOUR_AGENT_API_KEY_HERE — from your published agent dashboard

5 Restart Cursor

Restart Cursor to load the new MCP server configuration.

✅ Verification: In Cursor's MCP panel you should see one or two Oshaani servers connected. oshaani-agent-conversation lists chat/file tools; oshaani-agent-management lists agent CRUD tools.

4. Adding to Claude Desktop

Claude Desktop (Anthropic's official app) supports MCP servers through configuration files.

1 Locate Claude Config File

Find your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
2 Edit configuration

Add the Oshaani MCP servers (user + agent, or either one):

{
  "mcpServers": {
    "oshaani-agent-management": {
      "url": "https://mcp.oshaani.com/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_USER_API_KEY_HERE"
      }
    },
    "oshaani-agent-conversation": {
      "url": "https://mcp.oshaani.com/agent/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_AGENT_API_KEY_HERE"
      }
    }
  }
}
3 Replace API keys

Use your user key for /mcp and your published agent key for /agent/mcp.

4 Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.

5. Other MCP-Compatible Agents

The Oshaani MCP server follows the Model Context Protocol specification and should work with any MCP-compatible client. Here's a generic configuration:

Full configuration (both servers)

{
  "mcpServers": {
    "oshaani-agent-management": {
      "url": "https://mcp.oshaani.com/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_USER_API_KEY_HERE"
      }
    },
    "oshaani-agent-conversation": {
      "url": "https://mcp.oshaani.com/agent/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_AGENT_API_KEY_HERE"
      }
    }
  }
}

Conversation only (agent key)

{
  "mcpServers": {
    "oshaani-agent-conversation": {
      "url": "https://mcp.oshaani.com/agent/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_AGENT_API_KEY_HERE"
      }
    }
  }
}

Supported clients

💡 Tip: Match the URL to the key type:
  • https://mcp.oshaani.com/mcp → user API key
  • https://mcp.oshaani.com/agent/mcp → agent API key (published agent)
See Authentication Methods for header formats.

6. Authentication Methods

Both endpoints accept the same header formats. The key type (user vs agent) must match the endpoint.

Endpoint Key type Wrong key error
POST /mcp User API key Agent key rejected — use /agent/mcp
POST /agent/mcp Agent API key User key rejected — use /mcp

Method 1: Authorization header (ApiKey) — recommended

Authorization: ApiKey YOUR_API_KEY_HERE

Method 2: Authorization Header (Bearer)

Authorization: Bearer YOUR_API_KEY_HERE

Method 3: X-API-Key Header

X-API-Key: YOUR_API_KEY_HERE
📝 MCP config files: Put the key in the headers object as shown above. Some clients also accept api_key in the JSON-RPC body if headers are not supported.

Discovery: GET /auth/info (user key docs) · GET /auth/agent-info (agent key docs)

7. Testing Your Connection

Health check (no auth)

curl https://mcp.oshaani.com/health

List tools — user MCP (/mcp)

curl -s -X POST https://mcp.oshaani.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey YOUR_USER_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

List tools — agent MCP (/agent/mcp)

curl -s -X POST https://mcp.oshaani.com/agent/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey YOUR_AGENT_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

In your MCP client

Most MCP clients will show:

✅ Success Indicators:
  • Server appears as "connected" in your MCP client
  • Tools and resources are listed and available
  • You can execute MCP operations without errors

8. Troubleshooting

Wrong API key type

Problem: 401 with message about user vs agent key
Solutions:
  • Agent key on /mcp → switch URL to /agent/mcp
  • User key on /agent/mcp → switch URL to /mcp
  • Agent key but agent not published → publish the agent first

Connection issues

Problem: Cannot connect to MCP server
Solutions:
  • User MCP: https://mcp.oshaani.com/mcp
  • Agent MCP: https://mcp.oshaani.com/agent/mcp
  • Health: https://mcp.oshaani.com/health
  • Check DNS and firewall; confirm nginx proxies /agent/mcp

Authentication errors (general)

Problem: 401 Unauthorized or authentication failed
Solutions:
  • Verify your API key is correct (no extra spaces)
  • Check that the Authorization header format is correct
  • Ensure your API key hasn't been revoked or expired
  • Try regenerating your API key from the Oshaani platform

SSL/TLS Certificate Warnings

Problem: Certificate warnings in browser or client
Note: If you see certificate warnings, the server may be using a temporary self-signed certificate. This is normal during initial setup. For production use, ensure a valid Let's Encrypt certificate is installed.

MCP Client Not Recognizing Server

Problem: MCP client doesn't show the server or tools
Solutions:
  • Restart your MCP client after configuration changes
  • Verify the JSON configuration is valid (check for syntax errors)
  • Check client logs for error messages
  • Ensure your client supports HTTP/SSE transport (not just STDIO)

Getting Help

If you continue to experience issues:

  • Server logs: /var/log/mcp-server/ (includes mcp_server.log when file logging enabled)
  • Nginx: /var/log/nginx/mcp_oshaani_com_error.log
  • Platform: oshaani.com
  • MCP spec: modelcontextprotocol.io

Oshaani MCP Server Guide

/mcp · /agent/mcp · mcp.oshaani.com · oshaani.com