Connect Blogent to AI assistants via MCP

Connection contract

MCP endpoint

https://blogent.tools/mcp

Transport

Streamable HTTP over HTTPS. Send each JSON-RPC message with POST. GET returns 405; this server does not expose an SSE listener.

Protocol revisions

2025-06-18, 2025-11-25, and 2026-07-28. If sent, MCP-Protocol-Version must be one of these values.

Authentication

Authorization: Bearer <access_token>. Missing or expired credentials return 401 with a protected-resource metadata link.

Content

UTF-8 JSON-RPC 2.0. Send Content-Type: application/json and Accept: application/json, text/event-stream; Blogent responds with JSON.

Capabilities

Tools only. No resources, prompts, sampling, or server-initiated notifications.

OAuth authorization-code flow

Use a public OAuth client with PKCE S256. Preserve and verify state, and send the exact canonical MCP URL as resource in both authorization and token requests.

1. Request protected-resource and authorization-server metadata from the two well-known URLs.
2. Register the client with POST /oauth/register. Redirect URIs must use HTTPS, except HTTP is accepted for localhost loopback addresses.
3. Generate a 43–128 character PKCE verifier, derive its SHA-256 base64url challenge, and open GET /oauth/authorize in the user’s browser.
4. After approval, verify state and exchange the returned one-time code at POST /oauth/token. Authorization codes expire after 10 minutes.
5. Store tokens securely. Access tokens expire after 3600 seconds. Refresh with grant_type=refresh_token; every refresh rotates and invalidates the previous refresh token.
6. Revoke either token with POST /oauth/revoke when disconnecting the account.

OAuth endpoint reference

Copyable protocol examples

Replace uppercase placeholders. OAuth form endpoints accept standard form fields; MCP calls use JSON.

curl -X POST "https://blogent.tools/oauth/register" \
  -H "Content-Type: application/json" \
  --data '{
    "client_name": "Acme MCP Client",
    "redirect_uris": ["https://client.example.com/oauth/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'

GET https://blogent.tools/oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https%3A%2F%2Fclient.example.com%2Foauth%2Fcallback
  &scope=projects%3Aread%20projects%3Awrite%20billing%3Aread%20billing%3Awrite
  &state=RANDOM_OPAQUE_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fblogent.tools%2Fmcp

curl -X POST "https://blogent.tools/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=CLIENT_ID" \
  --data-urlencode "code=AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://client.example.com/oauth/callback" \
  --data-urlencode "code_verifier=PKCE_VERIFIER" \
  --data-urlencode "resource=https://blogent.tools/mcp"

curl -X POST "https://blogent.tools/mcp" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"acme-client","version":"1.0.0"}}}'

curl -X POST "https://blogent.tools/mcp" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -X POST "https://blogent.tools/mcp" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

curl -X POST "https://blogent.tools/mcp" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "create_project",
      "arguments": {
        "domain": "example.com",
        "company": "Example",
        "languages": ["en"],
        "company_description": "Factual context approved by the customer."
      }
    }
  }'

Tool input reference

Always treat the current tools/list response as the machine-readable source of truth: it includes inputSchema, outputSchema, and behavior annotations for every tool.

Project field reference

Unknown fields are rejected. create_project requires the first four fields; update_project.changes accepts any non-empty subset except domain.

Response envelope

Successful tool execution returns both human-readable content and machine-readable structuredContent. Business and validation failures are tool results with HTTP 200 and result.isError=true. Protocol failures use a JSON-RPC error object.

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "Project created without charging the user. Present billing plans next."}],
    "structuredContent": {"project": {}, "next_actions": []},
    "isError": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{"type": "text", "text": "The connected account did not grant the projects:write scope."}],
    "isError": true
  }
}

Errors, retries, and idempotency

End-to-end acceptance checklist

1. Discovery returns the production HTTPS issuer, MCP resource, endpoints, and supported scopes.
2. Dynamic registration succeeds and the client validates its OAuth state and PKCE verifier.
3. Token exchange, one refresh rotation, and revocation are verified without logging raw tokens.
4. initialize (for 2025 revisions) and tools/list succeed with the bearer token; every tool has input and output schemas.
5. A read-only call succeeds, while a missing scope produces result.isError=true.
6. A test project is created only after confirmation, then read back and updated by normalized domain.
7. Custom topics append without deleting existing titles and duplicate titles are ignored.
8. All billing plans are shown before the user explicitly selects a period.
9. Stripe test checkout is created, a same-period retry is reused, and payment is reported only after webhook confirmation.
10. Disconnect revokes the token, and subsequent MCP access returns 401.

Protocol background: Streamable HTTP, MCP authorization, and the MCP schema. Blogent behavior on this page takes precedence for this endpoint.