Smile Checks MCP Server

Model Context Protocol (MCP) server for the Smile Checks Integration API.

Hosted (Streamable HTTP): https://mcp.getsmilechecks.com — deployed on Google Cloud Run. See docs/mcp-server-operations.md for deploy/update/rollback commands.

Features

• 8 core API tools:
  • initiate_check
  • check_status
  • list_check_requests
  • get_check_request
  • get_reports
  • get_ai_assessment
  • cancel_check
  • get_credit_balance
• 2 convenience tools:
  • list_check_types
  • get_webhook_deliveries
• Local stdio mode for any MCP-compatible client that spawns a local process (e.g. Claude Desktop, Codex)
• Remote Streamable HTTP mode for any MCP-compatible client that supports a hosted URL (e.g. Cursor, Claude Desktop custom connector, Codex)

Install

cd mcp-server
npm install
npm run build

Run (stdio)

cd mcp-server
SMILE_API_KEY=your-api-key npm run start

Run (Streamable HTTP)

cd mcp-server
OAUTH_SHIM_SECRET=$(openssl rand -hex 32) PORT=8788 npm run start:http

The HTTP server does not take an API key at startup — each client supplies its own company key on every request (see Authentication below). OAUTH_SHIM_SECRET is required for the /register, /authorize, and /token OAuth shim endpoints to work; the server still starts without it, but those three routes will error. For hosting this in production, see docs/mcp-server-operations.md.

Stdio Config Example (local process)

Any MCP client that supports launching a local stdio server can point directly at dist/index.js. Config shape varies by client — consult your client's MCP documentation for exactly where this goes. Example, using the config format common to desktop AI clients:

{
  "mcpServers": {
    "smile-checks": {
      "command": "node",
      "args": ["/absolute/path/to/verifier-central/mcp-server/dist/index.js"],
      "env": {
        "SMILE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Hosted Config Example (Streamable HTTP)

Point your MCP client at https://mcp.getsmilechecks.com. Three ways to authenticate, depending on the client:

• Clients with a "Connect" / OAuth-style connector button (e.g. Claude Desktop's Connectors settings): add the URL and click Connect. This walks through the server's OAuth shim (see below) — you'll be prompted for your Smile Checks API key in a browser tab, and the client receives a token afterward. No beta or admin feature required.

• Clients with a "custom connector" / request-headers UI: add the URL, then configure x-api-key = your company API key as a request header. Support for this varies by client and may require a beta or admin-level feature — check your client's connector settings.

• Clients configured via a config.toml / config file with a bearer-token option: set the URL and point the bearer-token field at an environment variable holding your key, e.g.:

  [mcp_servers.smile_checks]
  url = "https://mcp.getsmilechecks.com"
  bearer_token_env_var = "SMILE_API_KEY"

• Clients with a plain MCP server URL field: add the URL and configure the x-api-key header per that client's connection settings.

Authentication

Your Smile Checks API key is found in the portal under Company Settings → Integrations.

• stdio: set the SMILE_API_KEY environment variable, or pass apiKey as a tool argument (legacy, still supported for backward compatibility).
• Streamable HTTP: send the key as an x-api-key header, or Authorization: Bearer <key>. The apiKey tool argument is not accepted over HTTP — credentials must come from the request, not from model-visible tool input.
• Streamable HTTP via OAuth shim: clients that only support a "Connect" button (no header UI) complete a standard OAuth 2.1 + Dynamic Client Registration flow against /register, /authorize, and /token (see src/oauth-shim.ts). /authorize collects the same company API key via a simple form, verifies it against the real API, and the resulting access token round-trips back to that key — there is no separate user identity system. Requires OAUTH_SHIM_SECRET to be set on the server (see Environment below).

The server forwards the resolved key as X-API-Key to https://api.getsmilechecks.com/functions/v1. All the same rate limits (120 req/min, 5,000 req/day) and company scoping apply as the REST API — the key is one key per company, shared by everyone who connects an AI client with it.

Environment (Streamable HTTP only)

| Variable | Required | Description | |---|---|---| | OAUTH_SHIM_SECRET | Yes, for the OAuth shim endpoints | HMAC signing key for OAuth shim codes/tokens (openssl rand -hex 32). Rotating it invalidates all outstanding shim-issued access/refresh tokens — clients re-run the Connect flow. |

Notes

• All Snowflake IDs must be treated as strings.
• get_webhook_deliveries requires the api-webhook-deliveries edge function in this repo.