totp_verify_sha256

Verify a time-based one-time password (TOTP) against a Base32-encoded secret using HMAC-SHA256.

Accepts tokens from the current window and one adjacent window on either side (±1 step skew) to handle clock drift.

Verification failures are not returned as MCP errors — they are represented as { "valid": false } so agents can handle them programmatically.

warning

SHA-256 TOTP is not widely supported by consumer authenticator apps. Only use this tool when the service explicitly requires HMAC-SHA256. For standard authenticator app compatibility, use totp_verify_sha1.

Parameters

Parameter	Type	Required	Description
secret	string	Yes	Base32-encoded TOTP secret, as exported by authenticator apps (e.g. JBSWY3DPEHPK3PXP). Case-insensitive.
token	string	Yes	The TOTP token to verify (e.g. "482910").
digits	integer	No	Number of digits expected in the token. Must be 6 or 8. Defaults to 6.
step	integer	No	Time step in seconds. Defaults to 30.
time	integer	No	Unix timestamp (seconds) to verify against. Omit to use the current system time.

Response

Field	Type	Description
valid	boolean	true if the token is correct within the ±1 time-step tolerance window.

Examples

Verify a token against a specific timestamp

{
	"secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",
	"token": "524938",
	"time": 1700000000
}

Result:

{
	"valid": true
}

---

Verify against the current time

{
	"secret": "JBSWY3DPEHPK3PXP",
	"token": "739104"
}

Result:

{
	"valid": true
}

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	A required argument is missing or the wrong type (e.g. secret or token is absent).	protocol error (invalid_params)
invalid_secret	secret is present but is not valid Base32.	tool error (isError)
internal_error	The system clock could not be read (only when time is omitted), or an unexpected server error occurred.	protocol error (internal_error)

info

Token mismatches are not MCP errors. They are returned as { "valid": false } so agents can handle them programmatically without catching exceptions.

Notes

• SHA-256 and SHA-1 produce different tokens. A token generated with totp_generate_sha256 must be verified with totp_verify_sha256.
• ±1 step tolerance is always applied.
• The secret is case-insensitive. It is uppercased internally before decoding.
• Use totp_generate_sha256 to generate tokens for testing, then totp_verify_sha256 to confirm they validate correctly.