Shield MCP API

Execution protection for AI agents via Model Context Protocol

Overview

The Shield MCP API provides AI assistants with idempotency and execution protection capabilities. Optimized for AI integrations using the MCP protocol over HTTP transport with JSON-RPC 2.0.

MCP Endpoint

https://mcp.ainoflow.io/mcp/v1/shield

Transport:

HTTP (SSE)

Configuration

OpenAI Agent Builder

Add MCP server in the UI dialog:

URL:

Label:

Authentication (Access token / API Key):

Claude Desktop

Add to your Claude Desktop configuration:

Cursor IDE

Add to your Cursor MCP configuration:

Available Tools

shield_acquire

Acquire a distributed lock for idempotency protection

key

required

- Unique lock identifier (max 512 chars)

ttl

optional

- TTL in seconds (default: 3600, max: 86400)

reference

optional

- Reference for audit

Example Usage:

Success Response:

Duplicate Response:

Check acquired field to determine if lock was obtained

shield_complete

Mark lock as completed. Sets TTL to 30 days for duplicate detection.

key

required

- Lock key

token

required

- Token from acquire

Example Usage:

Success Response:

shield_renew

Set new lock TTL (heartbeat). Capped to max_lifetime deadline.

key

required

- Lock key

token

required

- Token from acquire

ttl

optional

- New TTL in seconds (default: 3600)

Example:

Response (TTL capped):

capped: true means TTL was reduced to fit within max_lifetime deadline

shield_status

Check if lock exists and get remaining TTL

key

required

- Lock key

allowEmpty

optional

- If true, returns empty object instead of error when not found (default: false)

Example:

Response:

Available Resources

shield://{key}

Access lock status as a resource

MIME Type: application/json

Returns: {"exists": true, "expiresIn": 2400}

Use Cases for AI Assistants

Idempotent Task Execution

Ensure tasks run exactly once

Long-Running Tasks with Heartbeat

Protect multi-step operations

Check Before Action

Query lock status before operations

Parallel Agent Protection

Coordinate between multiple agents

Constraints and Limits

Key specifications for Shield operations

Key lengthMax 512 characters

Allowed charactersAny (URL-encode special chars in resource URIs)

Default lock TTL3600 seconds (1 hour)

Max lock TTL86400 seconds (24 hours)

Max lifetime deadline86400 seconds (24 hours from acquire)

Completed TTL2592000 seconds (30 days)

Token security128-bit cryptographically random

REST API Compatibility

Both MCP and REST APIs can be used simultaneously

REST API	MCP Tool
`POST /shield/{key}`	`shield_acquire`
`PUT /shield/{key}/complete`	`shield_complete`
`PUT /shield/{key}/renew`	`shield_renew`
`GET /shield/{key}`	`shield_status`

View full REST API Documentation →

Ready to integrate Shield MCP?

Get Started Free Back to MCP Hub