Documentation

The grammar checker is exposed to AI clients over Streamable HTTP at /mcp. Clients authenticate by signing you in; there are no API keys. All examples below use placeholders — replace anything in angle brackets.

1. Client configuration

{
  "mcpServers": {
    "ceo-owl": {
      "url": "https://<your-site>/mcp"
    }
  }
}

Your exact address and a copy button are on the connect page. On first use the client opens your browser so you can sign in and approve the connection.

2. Discovery

After initialize, a tools/list request returns one tool, check_grammar, with its input schema.

3. Calling the tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "check_grammar",
    "arguments": {
      "text": "<your english text>",
      "language": "en",
      "include_suggestions": true,
      "include_rule_ids": true
    }
  }
}

Argument	Required	Meaning
`text`	Yes	The English text to check, up to 10,000 characters.
`language`	No	Only `en` is accepted. Anything else is refused.
`include_suggestions`	No	Include replacement text for each finding. Defaults to true.
`include_rule_ids`	No	Include the Harper rule identifier. Defaults to true.

4. Successful response

{
  "success": true,
  "contract_version": "1",
  "language": "en",
  "document_length": 42,
  "issue_count": 1,
  "processing_ms": 18,
  "issues": [
    {
      "id": "<stable-id>",
      "rule_id": "<rule-id>",
      "category": "grammar",
      "message": "<human readable explanation>",
      "start": 10,
      "end": 13,
      "original_text": "<span text>",
      "suggestions": ["<replacement>"],
      "safe": true
    }
  ]
}

Findings are sorted deterministically: ascending start, then ascending end, then rule_id (findings without a rule identifier last). Identical tuples keep the order the engine emitted them in, so repeating the same request returns byte-identical output. Offsets are character indexes into the text you sent. A finding is safe when it has exactly one unambiguous replacement.

5. Error responses

Not signed in

{
  "success": false,
  "contract_version": "1",
  "error": {
    "code": "unauthorized",
    "message": "Sign in to this app to use the grammar checker."
  }
}

Rate limited

{
  "success": false,
  "contract_version": "1",
  "error": {
    "code": "rate_limited",
    "message": "Hourly limit reached. Try again in <seconds> seconds.",
    "retry_after_s": 1800
  }
}

Wait retry_after_s seconds before retrying. The default allowance is 60 checks per hour per account.

Unsupported language

{
  "success": false,
  "contract_version": "1",
  "error": {
    "code": "unsupported_language",
    "message": "Only English ('en') is supported."
  }
}

Other codes: invalid_input (empty or non-text input), too_large (over the character limit), timeout (the check took longer than 10 seconds) and internal.

6. Disconnecting

Revoking a client stops it from renewing access, but an access token it already holds stays valid until it expires — up to about one hour.

7. Privacy

Text sent to the tool is held in memory for the length of the request and is never stored or logged. Only anonymous counters are recorded. Read the privacy note.