Integrate Using Cursor / Claude Code (MCP Server)

Overview

The RiskOS™ MCP Server connects AI development tools like Cursor and Claude Code to your RiskOS™ account. Use it to:

Quickstart

Connect your AI development tool to the RiskOS™ MCP Server in four steps. Each step links to more detailed information in the following sections.

  1. Generate an MCP Server Key. In the RiskOS™ Dashboard, go to Developer Workbench > API & SDK Keys, create a key, and copy the token. See MCP keys.

  2. Add the server to your client. Configure your MCP client with the Sandbox base URL https://mcp.riskos.socure.com/sandbox and your key as a bearer token. See Client configuration examples.

  3. Run your first prompt. Start a session in your client and ask a question such as "What use cases are configured for my account?"

  4. Confirm the response. The assistant calls the list_usecases tool and returns your account's use cases. If your client cannot connect, see Troubleshooting.

Example response:

Your account has the following use cases configured:
- consumer_onboarding
- business_onboarding
- login_authentication

Key features

Agents can retrieve the full RiskOS™ documentation set: concepts, fields, workflows, and API behavior.

Retrieve the current RiskOS™ OpenAPI specification for code generation, validation, or starting a new integration. You can also browse the API Reference directly.

List the use cases and workflows configured in your RiskOS™ account to confirm setup and reference workflow identifiers programmatically.

The server includes prompts tailored for RiskOS™ development, helping agents provide accurate, implementation-ready guidance.

📘

Note:

MCP Server access uses MCP Server Keys for authentication, including for organizations that sign in to RiskOS™ using Single Sign-On (SSO). See MCP keys.

How it works

The RiskOS™ integration ecosystem uses a hybrid architecture of Logic and Data to provide AI assistants with both procedural expertise and real-time environment context.

High impact: the RiskOS™ Integration Skill

The RiskOS™ Integration Skill is a critical feature, acting as the "operating manual" for your assistant to integrate with RiskOS™. It defines standard integration patterns to ensure your agent follows best practices for integration in a guided path rather than guessing integration steps.

Install from here RiskOS™ Integration Skill

RiskOS™ MCP Server (the "Data Layer")

The RiskOS™ MCP Server provides an interface to your environment, acting as the dynamic data source for all development tasks.

Component comparison

Feature RiskOS™ Agent Skill (Logic) RiskOS™ MCP Server (Data)
Role Procedural logic and expert instructions. Standardized interface for platform data.
Primary Goal Teaches the agent how to implement. Shows the agent what is configured.
Capabilities Decision patterns and error handling. Live docs, API schemas, and workflows.
Data Scope Static logic and reference artifacts. Dynamic platform state.

📘

Note:

The RiskOS™ MCP Server provides documentation, schemas, workflow metadata, and webhook management. It does not execute transactions or evaluations.

MCP keys

RiskOS™ supports MCP Server Keys for authenticating to the RiskOS™ MCP Server. MCP Server Keys provide a secure, streamlined authentication method and enable MCP Server access for all customers, including organizations that use Single Sign-On (SSO).

⚠️

Warning:

Username and password authentication for the MCP Server is no longer supported after July 21, 2026.

Manage MCP server keys

Create and manage MCP Server Keys from the MCP Server Keys section of the RiskOS™ Dashboard, under Developer Workbench > API & SDK Keys. Each key includes:

You can securely view and copy the token when configuring your MCP clients.

Install and configure

The RiskOS™ MCP Server exposes a simple HTTP interface compatible with any MCP-enabled client, including VS Code, Cursor, and other AI-driven development tools. Once configured, your AI assistant can automatically access RiskOS™ documentation, API schemas, and development guidance.

The MCP Server provides separate endpoints for the Sandbox and Production environments. Use the Sandbox endpoint for testing and integration, and the Production endpoint for live traffic. Authenticate to either environment with your MCP Server Key.

Setting Description Value
Protocol All MCP requests are sent over standard HTTP. HTTP
Base URL — Sandbox Endpoint for the Sandbox environment, used for testing and integration. https://mcp.riskos.socure.com/sandbox
Base URL — Production Endpoint for the Production environment, used for live traffic. https://mcp.riskos.socure.com/prod
Authentication Token-based authentication using an MCP Server Key. Authorization: Bearer YOUR_MCP_SERVER_KEY

Client configuration examples

📘

Note:

Claude Desktop

Claude uses a static configuration for MCP servers. Because Claude does not support interactive credential prompts, you must provide your MCP Server Key directly in the server configuration.

Prerequisites

Configure the MCP server

  1. Copy your MCP Server Key from Developer Workbench > API & SDK Keys in the RiskOS™ Dashboard. If you don't have one yet, see MCP keys to create one.

  2. In Claude Desktop, go to Settings > Developer and click Edit Config. This will take you to the Claude Desktop config file in your filesystem claude_desktop_config.json.

  3. Paste the following configuration into the mcpServers object. Replace YOUR_MCP_SERVER_KEY with the token from Step 1.

{
     "mcpServers": {
       "socure-dev-assist": {
         "command": "npx",
         "args": [\
           "-y",\
           "mcp-remote",\
           "https://mcp.riskos.socure.com/sandbox",\
           "--header",\
           "Authorization: Bearer YOUR_MCP_SERVER_KEY"\
         ]
       }
     }
}

Note: This example connects to the Sandbox environment. To connect to Production, use https://mcp.riskos.socure.com/prod.

  1. Restart Claude to apply the configuration.

  2. Once connected, start a new session with Claude to call RiskOS™ MCP tools using natural-language prompts.

Claude Code (CLI)

Claude Code is a command-line interface (CLI) agent that runs directly in your terminal.

Prerequisites

  1. Export the key as an environment variable in your shell profile (e.g., ~/.zshrc or ~/.bash_profile):
export RISKOS_MCP_KEY="YOUR_MCP_SERVER_KEY"
  1. Restart your terminal, then run the following command to add the RiskOS™ server to Claude Code. This command uses the variable created in Step 2 to authorize the connection.
claude mcp add --transport http socure-dev-assist \
     https://mcp.riskos.socure.com/sandbox \
     --header "Authorization: Bearer $RISKOS_MCP_KEY"

Note: This example connects to the Sandbox environment. To connect to Production, use https://mcp.riskos.socure.com/prod.

  1. Verify the connection:
claude mcp list
  1. Launch the agent by typing claude. Then use natural language prompts to interact with RiskOS™ MCP tools.

Cursor

Cursor uses static configuration and requires credentials pre-configured in the settings.

Prerequisites

Configure the MCP server

Installation

  1. Copy your MCP Server Key from Developer Workbench > API & SDK Keys in the RiskOS™ Dashboard. If you don't have one yet, see MCP keys to create one.

  2. Go to Cursor Settings > Tools & MCP.

  3. Click New MCP Server to update your Cursor MCP configuration file at ~/.cursor/mcp.json. Replace YOUR_MCP_SERVER_KEY with the token from Step 1.

{
     "mcpServers": {
       "socure-dev-assist": {
         "type": "http",
         "url": "https://mcp.riskos.socure.com/sandbox",
         "headers": {
           "Authorization": "Bearer YOUR_MCP_SERVER_KEY"
         }
       }
     }
}

Note: This example connects to the Sandbox environment. To connect to Production, use https://mcp.riskos.socure.com/prod.

  1. Restart Cursor to apply the configuration.

  2. Once connected, use Chat or Agent mode in Cursor to call RiskOS™ MCP tools using natural-language prompts.

VS Code

VS Code supports interactive credential prompts using inputs in mcp.json.

Prerequisites

  1. Open VS Code and create a .vscode/mcp.json file in your project root with the following configuration:
{
     "inputs": [\
       {\
         "id": "mcpKey",\
         "type": "promptString",\
         "description": "RiskOS MCP Server Key",\
         "password": true\
       }\
     ],
     "servers": {
       "socure-dev-assist": {
         "type": "http",
         "url": "https://mcp.riskos.socure.com/sandbox",
         "headers": {
           "Authorization": "Bearer ${input:mcpKey}"
         }
       }
     }
}

Note: This example connects to the Sandbox environment. To connect to Production, use https://mcp.riskos.socure.com/prod.

  1. Save the file, then open the Command Palette with Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows/Linux.

  2. Run MCP: List Servers, select socure-dev-assist, then start the server.

  3. VS Code will detect the server and prompt for your MCP Server Key on first use.

  4. Once connected, you can call any RiskOS™ MCP tool from VS Code’s AI panel using natural-language prompts.

Troubleshooting

Use the following table to resolve common connection issues.

Symptom Likely cause Resolution
401 Unauthorized, or the client reports an invalid token The MCP Server Key is inactive, mistyped, or revoked. Confirm the key status is Active in Developer Workbench > API & SDK Keys, and that the full token is set as the bearer token.
The client connects to the wrong environment The configuration uses the wrong base URL. Use https://mcp.riskos.socure.com/sandbox for Sandbox or https://mcp.riskos.socure.com/prod for Production.
The server fails to start, or mcp-remote errors on launch Node.js is older than the required version. Install Node.js v20.18.1 or later, then restart your client.
The assistant does not list any RiskOS™ tools The client has not loaded the server, or the session predates setup. Restart your MCP client and start a new session. Confirm the server appears in your client's MCP server list.
list_testcases or integration_checklist returns nothing These tools are available in the Sandbox environment only. Connect to the Sandbox endpoint (https://mcp.riskos.socure.com/sandbox) to use these tools.
The assistant returns no workflows No workflows are active for the account. Activate a workflow in the RiskOS™ Dashboard, then retry.

Available tools

The RiskOS™ MCP Server provides the following tools for retrieving documentation, exploring workflows, and supporting integration development. The Environment column shows where each tool is available.

Tool Description Environment
ask_docs General RiskOS™ documentation, feature explanations, and API guidance (not account-specific). Sandbox, Production
add_webhook Create and configure a new webhook endpoint for this account. Sandbox, Production
update_webhook Modify an existing webhook configuration for this account. Sandbox, Production
list_webhooks Retrieve all webhooks currently configured in this account. Sandbox, Production
list_events Retrieve webhook events available for RiskOS™ in general. Sandbox, Production
list_testcases Retrieve test cases configured in this account to help with API Integration. Sandbox only
list_usecases Retrieve use cases configured for this account. Sandbox, Production
list_workflows Retrieve workflows configured for this account. Sandbox, Production
integration_checklist View integration steps configured for this account to help integrate with RiskOS™. These steps are specific to the customer’s workflow. Sandbox only

Example usage:

Advanced usage:

Prompts

Prompts guide how the assistant reasons, not what data it can access. They do not call MCP tools directly.

These modes help the assistant produce higher-quality explanations or integration-level code depending on your task.

Prompt Description
documentation Switches the assistant into “RiskOS™ documentation expert” mode. Best for conceptual explanations, workflow overviews, and clarifying platform behavior.
integration Switches the assistant into “RiskOS™ integration engineer” mode. Best for generating code samples, request payloads, API calls, and step-by-step implementation guidance.

Example usage:

Resources

Resources expose static, machine-readable artifacts suitable for code generation, schema validation, and IDE integration.

Resource Description
riskos_openapi_spec Returns the complete RiskOS™ OpenAPI specification, including endpoints, schemas, and workflow representations. Useful for generating typed clients or validating request/response structures. Also available in the API Reference.

Example usage:

Security best practices

The RiskOS™ MCP Server is designed for secure development assistance. The following best practices help ensure credentials and environments remain protected.

Protect your MCP Server Key

Limit key exposure

Understand data access boundaries

The MCP server can access:

The server does not:

Treat AI output as advisory

Secure your development environment

Next steps