jwt_verify_hs512

Verify the signature of a JWT (JSON Web Token) using the HS512 (HMAC-SHA512) algorithm. Returns valid: true/false along with the decoded header and payload on success.

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

Parameters

Parameter	Type	Required	Description
token	string	Yes	The JWT string to verify.
secret	string	Yes	HMAC shared secret used to verify the signature. Must match the secret used to sign the token.
validate_claims	boolean	No	When true, also validates exp (expiry) and nbf (not-before) claims. Defaults to false so expired tokens can still be inspected if the signature is valid.

Response

Field	Type	Description
valid	boolean	true if the signature is correct (and claims pass when validate_claims is true).
header	object	The decoded JWT header. Only present when valid is true.
payload	object	The decoded JWT payload. Only present when valid is true.
error	string	Human-readable reason for failure. Only present when valid is false.

Examples

Verify a token

{
	"token": "eyJhbGciOiJIUzUxMiJ9...",
	"secret": "my-shared-secret"
}

Result (valid):

{
	"valid": true,
	"header": { "alg": "HS512" },
	"payload": { "sub": "user_42", "role": "admin", "exp": 9999999999 }
}

Result (invalid — wrong secret or tampered token):

{
	"valid": false,
	"error": "InvalidSignature"
}

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	token or secret is missing, or an argument is the wrong type.	protocol error (invalid_params)
internal_error	An unexpected server error.	protocol error (internal_error)

info

Signature failures and claim validation failures are not MCP errors. They are returned as { "valid": false, "error": "..." } so agents can handle them programmatically without catching exceptions.

Notes

• validate_claims defaults to false. This means an expired token is still accepted as long as the signature is correct. Set validate_claims: true to enforce exp and nbf.
• Audience (aud) is never required. Tokens that contain an aud claim are accepted without specifying a required audience.
• Only HS512 tokens can be verified with this tool. For other algorithms use jwt_verify_hs256 or jwt_verify_hs384. Use jwt_decode to inspect the payload of any token without signature verification.
• Use jwt_sign_hs512 to create tokens for testing, then jwt_verify_hs512 to confirm they validate correctly.