MCP Server Getting Started Guide

Prerequisites

To get started using the Socotra MCP server, you'll need a valid Socotra business account and login credentials. Our MCP server uses OAuth 2.1 for authentication and authorization. Contact your Socotra representative to request access for your business account.

Users must possess the required permissions and tenant assignments to perform certain actions through the Socotra MCP server.

Refer to our documentation on Role-Based Access Control for more information.

Installation

The Socotra MCP server currently supports the following applications:

Cursor
Claude
Codex

Cursor

Download and install Cursor
If you already have Cursor, make sure to update it to the latest version
Open Cursor
Click the Open Settings button in the upper right corner of the window (displayed as a gear icon)
Navigate to MCP & Integrations > New MCP Server
Paste this JSON into mcp.json:

{
	"mcpServers": {
		"SocotraSandbox": {
			"url": "https://mcp-sandbox.socotra.com/mcp"
		}
	}
}

Save the file
Go back to the MCP & Integrations tab
You'll see SocotraSandbox listed in MCP Tools
Click the Connect button
The Socotra authentication page will open in your browser
Enter your business account name, followed by your username and password
Click the Authorize button
You should see a message indicating that authorization was successful
Open Cursor, and verify that the green circle appears next to SocotraSandbox listed in MCP Tools
Open a new chat by clicking the Toggle AI Pane button in the upper right corner of the window, then clicking the Create a new chat button
Click the @Add Context button
Select mcp.json
Cursor will now be able to use the Socotra MCP server as you send prompts

Refer to the Cursor MCP configuration guide for more information.

Claude

Download and install Claude Desktop
If you already have Claude Desktop, make sure to update it to the latest version
Install Node.js and npm
Open Claude Desktop

Then, for pro accounts:

Navigate to Settings > Connectors
Click the Add custom connector button
Set the name as Socotra and the URL as https://mcp-sandbox.socotra.com/mcp
Click the Add button
Click the Connect button
The Socotra authentication page will automatically open in your browser
Enter your Business Account name, followed by your username and password
Click the Authorize button
You should see a message indicating that authorization was successful
Open Claude Desktop
Open a new chat by clicking the New chat button
Click the Search and tools button
You should see the Socotra MCP server toggled on
Click on the Socotra MCP server to view available tools and toggle them as needed
Claude will now be able to use the Socotra MCP server as you send prompts

Or, for free accounts:

Navigate to Settings > Developer
Click the Edit config button
Paste this JSON into claude_desktop_config.json:

{
	"mcpServers": {
		"Socotra": {
			"command": "npx",
			"args": ["-y", "mcp-remote", "https://mcp-sandbox.socotra.com/mcp"]
		}
	}
}

Save the file
Restart Claude Desktop
The Socotra authentication page will automatically open in your browser
Enter your Business Account name, followed by your username and password
Click the Authorize button
You should see a message indicating that authorization was successful
Open Claude Desktop
Open a new chat by clicking the New chat button
Click the Search and tools button
You should see the Socotra MCP server toggled on
Click on the Socotra MCP server to view available tools and toggle them as needed
Claude will now be able to use the Socotra MCP server as you send prompts

Refer to the Claude MCP configuration guide for more information.

Codex

Install Codex
If you already have Codex, make sure to update it to the latest version
Open the Codex configuration file by executing the following command from your terminal:

~/.codex/config.toml

Add the following lines to the file:

[mcp_servers.SocotraSandbox]
url = "https://mcp-sandbox.socotra.com/mcp"

Save the file
Log in to the Socotra Sandbox environment by executing the following command from your terminal:

codex mcp login SocotraSandbox

Codex will display an authorization link
Open the link in a web browser and enter the following information: Business account name, username, and password
Verify your connection by executing the following command from your terminal:

codex mcp list

Restart Codex

Refer to the Codex MCP configuration guide for more information.

Next Steps

MCP Server Prompt Examples