Client Setup

Hosted at https://dev.mcp.ivalt.com — SDK: @ivalt/agent-auth on npm.

This guide shows how to connect an MCP client to the iVALT-MCP server. The server can be reached over STDIO (for local desktop clients) or HTTP/SSE (for remote deployments like https://dev.mcp.ivalt.com).

Live endpoint: https://dev.mcp.ivalt.com/mcp ( https://dev.mcp.ivalt.com, http://dev.mcp.ivalt.com → https). Health: https://dev.mcp.ivalt.com/health.

Choose a transport

STDIO setup

Use the STDIO binary from the @ivalt/agent-auth package. The client should start it with node and pass the required environment variables in env.

Example claude_desktop_config.json

{
  "mcpServers": {
    "ivalt-mcp": {
      "command": "node",
      "args": [
        "node_modules/@ivalt/agent-auth/bin/ivalt-mcp.js"
      ],
      "env": {
        "IVALT_DEFAULT_MOBILE": "+12025550123",
        "IVALT_API_KEY": "your-ivalt-api-key",
        "IVALT_REQUEST_FROM": "My App",
        "IVALT_DEFAULT_FACTORS": "biometric,location,device"
      }
    }
  }
}

Notes:

• The args path is relative to the project root. Use an absolute path if your client starts the process from a different working directory.
• IVALT_DEFAULT_MOBILE is optional. If you omit it, every tool call must include approver_mobile.
• IVALT_API_KEY is optional. Leave it out to use the public demo proxy.
• See Configuration for all environment variables.

Generic mcp.json shape

Other clients use the same mcpServers object but may name the file mcp.json, .cursor/mcp.json, .windsurf/mcp.json, etc.

{
  "mcpServers": {
    "ivalt-mcp": {
      "command": "node",
      "args": ["node_modules/@ivalt/agent-auth/bin/ivalt-mcp.js"],
      "env": {
        "IVALT_DEFAULT_MOBILE": "+12025550123"
      }
    }
  }
}

HTTP/SSE setup

Point the client at the /mcp endpoint (hosted: https://dev.mcp.ivalt.com/mcp, or locally http://localhost:8080/mcp). If MCP_AUTH_TOKEN is set, pass it as a Bearer token. See @ivalt/agent-auth for SDK alternatives.

Example mcp.json (Production)

{
  "mcpServers": {
    "ivalt-mcp": {
      "url": "https://dev.mcp.ivalt.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

For local Docker Compose:

{
  "mcpServers": {
    "ivalt-mcp": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

• url must end in /mcp.
• Live https://dev.mcp.ivalt.com/mcp requires Authorization: Bearer <token> (see docs/configuration.md).
• MCP_AUTH_TOKEN is optional locally. If not set, omit the Authorization header.
• See Deployment for TLS/Nginx setup and Configuration for the token.

Passing the mobile number from the client

Even if IVALT_DEFAULT_MOBILE is set, you can override the approver phone on each call by passing approver_mobile in the tool arguments:

{
  "action": "Approve production deploy",
  "approver_mobile": "+12025550123",
  "reason": "Urgent hotfix"
}

If IVALT_DEFAULT_MOBILE is not configured, approver_mobile is required.

Verification

STDIO

Restart the client and check that the ivalt-mcp tools appear in the tool list (request_approval, request_approval_async, check_status).

HTTP

Live:

curl https://dev.mcp.ivalt.com/health
curl -X POST https://dev.mcp.ivalt.com/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

For local:

curl http://localhost:8080/health
curl http://localhost:8080/mcp -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

If MCP_AUTH_TOKEN is not set, omit the Authorization header. http://dev.mcp.ivalt.com will 301 to https.