Class McpRateLimiter

java.lang.Object
com.mcpdbwizard.pub.McpRateLimiter
public final class McpRateLimiter extends Object
A token bucket bounding how often a generated MCP server starts work.

Configured from the environment: MCP_RATE_LIMIT is the sustained rate in calls per second and MCP_RATE_BURST the bucket depth — how many may arrive at once after a quiet spell. Unset means unlimited, so an existing deployment behaves exactly as before and there is no new config-file surface to carry.

What this does and does not protect against

It bounds how often calls start. It does nothing about how long one runs, and that is the case that actually pins a pooled connection — a single expensive query holds a factory for as long as Oracle takes, whatever the request rate. A statement timeout is the tool for that; see docs/mcp-rate-limiting-plan.md. This is worth knowing before treating a configured rate limit as protection against a runaway agent.

Refusal is deliberately distinct from pool exhaustion. Both shed load, but one is policy and the other is saturation, and an operator reading the log needs to tell them apart. Copyright 2003-2026 ATB Consultancy Services Ltd (formerly Orinda Software Ltd, Dublin, Ireland)

  • Field Details

    • RATE_VARIABLE

      public static final String RATE_VARIABLE
      Sustained calls per second. Unset or empty means no limit.
      See Also:

    • BURST_VARIABLE

      public static final String BURST_VARIABLE
      Bucket depth — how many calls may arrive at once. Defaults to one second's worth.
      See Also:

  • Method Details

    • disabled

      public static McpRateLimiter disabled()
      A limiter that permits everything, for when no rate is configured.

    • of

      public static McpRateLimiter of(double theRateValue, double theBurstValue)
      Build one from numbers rather than from the environment.

      The generated server has exactly one limiter and reads it from the environment. The web application needs one per caller, built from settings it has already parsed, so it needs a factory that takes values. Same bucket, same arithmetic — only the source of the numbers differs.

      Parameters:
      theRateValue - sustained permits per second; zero or less yields disabled()
      theBurstValue - bucket depth; raised to 1 if smaller, since a bucket that cannot hold a single permit would refuse everything

    • fromEnvironment

      public static McpRateLimiter fromEnvironment()
      Build from the environment.
      Throws:
      IllegalArgumentException - if a variable is set but unusable — a mistyped limit must stop start-up rather than silently leave the server unlimited

    • isEnabled

      public boolean isEnabled()
      Whether a limit is in force.

    • getRatePerSecond

      public double getRatePerSecond()

    • getBurst

      public double getBurst()

    • tryAcquire

      public boolean tryAcquire()
      Take one token if there is one.
      Returns:
      true when the call may proceed; false when it should be refused

    • toString

      public String toString()
      How the limiter describes itself in the log at start-up.
      Overrides:
      toString in class Object