totp_verify_sha1

Verify a time-based one-time password (TOTP) against a Base32-encoded secret using HMAC-SHA1 — the RFC 6238 default algorithm used by Google Authenticator, Authy, and the vast majority of TOTP-enabled services.

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

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

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. "287082").
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 the current time

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

Result (valid):

{
	"valid": true
}

Result (invalid — wrong token or expired beyond ±1 step):

{
	"valid": false
}

---

Verify against a known RFC 6238 test vector

{
	"secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",
	"token": "287082",
	"time": 59
}

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-1 is the correct choice for most services. Use totp_verify_sha1 for any token produced by a standard authenticator app unless the service documentation explicitly states a different algorithm.
• ±1 step tolerance is always applied. A token generated in the immediately preceding or following 30-second window is accepted. Tokens from windows further away are rejected.
• The secret is case-insensitive. It is uppercased internally before decoding.
• Use totp_generate_sha1 to generate tokens for testing, then totp_verify_sha1 to confirm they validate correctly.
• For other algorithms use totp_verify_sha256 or totp_verify_sha512.