Public MCP evidence service
The public demo and usage evidence surface are deployed at mcp.knwn.app.
KNWN ENGINEERING CASE STUDY
How we built an MCP server for KNWN Visibility.
We built seven focused, read-only tools around KNWN Visibility while preserving its existing identity and tenant boundaries. The public evidence service is live; customer account linking remains gated until the production OAuth configuration passes readiness.
Internal KNWN implementation
Source and deployment reviewed
No invented client ROI
Designed account-linked request path
Read-only by design
01
AI client
ChatGPT, Claude, or another compatible host
02
OAuth + PKCE design
Exact resource and one read-only scope
03
Visibility MCP
Seven focused tools and tenant checks
04
KNWN API
Live product data from authorized sites
No direct database connection
No write tools at launch
STATUS AT REVIEW DATE
What is live, what is deployed, and what we are not claiming.
Reviewed against the three implementation repositories and the KNWN Railway production project on August 16, 2026.
Visibility connector and backend handoff
The connector routes, seven tools, OAuth server code, dashboard consent handoff, and KNWN backend grant logic are present in the deployed repository revisions.
Customer account linking
At the review date, /knwn/readyz reported oauth_configuration_invalid. Customer account linking is not production-ready until that gate passes.
7read-only launch tools
1OAuth permission scope
0write tools at launch
30day analytics retention policy
THE PRODUCT PROBLEM
Give an AI assistant useful product access without broadening customer access.
KNWN Visibility already had live sites, visibility summaries, gaps, questions, page recommendations, and saved strategies. The challenge was not converting every backend endpoint into a tool. It was exposing a small set of useful customer jobs while keeping the existing KNWN product in control.
The MCP could not receive a customer's password, reuse a normal dashboard session, connect directly to regional databases, or trust an arbitrary site_id. It also needed analytics that explained real tool behavior without pretending to see the model's hidden reasoning or the entire host conversation.
We treated the MCP as a new permissioned product surface, not as a thin protocol wrapper around the API.
THE TOOL SURFACE
Seven jobs, one read-only scope.
Every launch tool declares knwn.visibility.read. No tool changes data, spends credits, starts a background job, or publishes content.
| Tool | What it lets the authenticated customer ask |
|---|---|
list_sites | List the KNWN sites the authenticated account can access and expose their current summary scores. |
get_visibility_overview | Return the selected site's visibility overview and recent direction from the KNWN API. |
get_visibility_gaps | Show missing, weak, or defended visibility opportunities for an authorized site. |
get_trending_questions | Return questions that create a visibility opportunity for the selected site. |
get_page_recommendations | Return whitelisted recommendations for a page proven to belong to the selected site. |
get_strategies | Read saved KNWN action plans and their current status. |
get_usage_snapshot | Explain what the MCP received, called, returned, and observably struggled with. |
CREDENTIAL BOUNDARY
The AI client token is never the KNWN product credential.
The implemented account-linking design separates the public MCP authorization from the private, read-only connection used against the fixed KNWN API origin.
AI client credential
The account-linking design issues a short-lived opaque token only for the exact MCP resource. It is not accepted as a normal KNWN API token.
KNWN connection credential
After approval, the design exchanges a single-use PKCE-bound handoff for a separate read-only credential and encrypts it at rest.
KNWN product systems
The connector calls the fixed api.knwn.app origin. Existing backend authorization remains the source of truth.
This sequence is implemented in code, but general customer rollout remains blocked while the production readiness endpoint reports an OAuth configuration error.
01
The client discovers the protected resource and authorization server metadata.
02
It begins an authorization-code request with PKCE S256, the exact MCP resource, and knwn.visibility.read.
03
The dashboard retrieves verified transaction details from the MCP instead of trusting display fields in the URL.
04
After the signed-in customer approves, KNWN creates a 90-second, single-use handoff code bound to the transaction, scope, resource, and user.
05
The MCP exchanges the handoff server to server and stores the resulting KNWN connection credential encrypted.
06
The AI client receives its separate short-lived access token and rotating refresh token family.
TENANT ENFORCEMENT
A valid token does not automatically authorize a site or page.
Before a site-specific tool runs, the connector obtains the authenticated user's allowed-site list and rejects any identifier that is not present. Before a page-specific request, it separately proves that the page belongs to the selected site.
An inaccessible identifier receives the same generic not-found response whether or not the underlying object exists. That prevents the tool from becoming an object-discovery side channel.
Endpoints intentionally excluded
- Score-history and competitor endpoints that do not consistently enforce site ownership.
- Internal agent endpoints that depend on a shared key instead of a user-bound tenant check.
- Write and generation endpoints that can spend credits, enqueue work, or change customer data.
TRUTHFUL MCP ANALYTICS
Measure what the tool can actually observe.
The analytics layer is included in every business tool. Analytics-read calls are excluded so opening a report cannot inflate usage or extend the observed activity span.
Tool execution evidence
- Tool name, start, completion, latency, result count, and error class.
- Selected functional arguments received by the tool capture rule.
- Authorized KNWN site attribution from the verified OAuth principal.
- Business outcome and observable friction such as missing input, partial results, timeouts, rate limits, or repeated calls.
Data the MCP does not have
- The full user's exact prompt in every host.
- The complete ChatGPT or Claude conversation.
- True host-session duration.
- Model chain of thought or hidden reasoning.
- Authorization headers, tokens, cookies, full upstream responses, raw email addresses, or IP addresses.
Execution
Tool completion
Did the tool return normally?
Business result
Full resolution
Did the terminal call fully satisfy the request?
Honest diagnosis
Completion and fulfillment stay separate
A partial result can be technically correct without fully resolving the task.
TESTING AND FAILURE CASES
The implementation is tested around the boundaries most demos skip.
The repository test suite covers identity, tenant access, redaction, protocol behavior, response minimization, analytics storage, and observable failure states.
Secret redaction
Authorization headers, OAuth tokens, API keys, cookies, full results, raw email addresses, and IP addresses are excluded from analytics.
Tenant enforcement
Tests cover inaccessible site and page identifiers, authorized-site lookup, response minimization, and generic not-found behavior.
Protocol compatibility
The server covers current Streamable HTTP behavior, legacy initialization, metadata, request headers, structured results, and tool errors.
Failure behavior
Coverage includes plan gates, missing input, empty and partial results, repeated calls, storage failure, rate limits, and downstream errors.
THREE REPOSITORIES, ONE IMPLEMENTATION
The product, MCP, analytics, and public proof remain separable.
caspianmoon/aieo-site-sense
The v2 branch owns KNWN grants, the dashboard consent handoff, regional authorization checks, short-lived MCP credentials, refresh-family rotation, and revocation.
caspianmoon/knwn-mcp-analytics
The main branch owns the remote MCP routes, seven tools, OAuth server, encrypted connection handling, rate limits, analytics contract, evidence demo, and tests.
caspianmoon/aieo-ai-clarity
The main branch owns this indexable case study, its internal links, structured data, conversion tracking, sitemap record, and commercial handoff.
Public websiteknwn.app
Product APIapi.knwn.app
Dashboard consentdash.knwn.app
MCP evidence servicemcp.knwn.app
WHAT WE LEARNED
The hard part was not exposing JSON-RPC.
The valuable engineering work sat in permission design, credential separation, object-level authorization, truthful analytics, and safe failure behavior.
Separate the client token from the product credential
An AI client should not receive a reusable KNWN session or a general API credential. The MCP token and the upstream connection serve different purposes and have different audiences.
Authorize the object, not only the request
A valid user token is insufficient. Every site-specific call checks the account's current site list, and every page-specific call proves the page belongs to the selected site.
Small tool surfaces are easier to secure and evaluate
The launch surface exposes seven jobs rather than mirroring the full API. Endpoints without consistent object authorization are intentionally excluded.
Analytics must distinguish execution from fulfillment
A partial result can be a correctly completed tool call without fully resolving the user's request. Tool completion and full resolution are reported separately.
LIMITS AND CURRENT BOUNDARY
What this implementation does not prove.
- It does not prove a client revenue increase, productivity percentage, ranking improvement, or universal delivery timeline.
- It does not make every KNWN API endpoint safe for AI access.
- It does not expose write tools in the launch surface.
- It does not claim full-prompt, full-conversation, host-session, or hidden-reasoning visibility.
- The public evidence service is live, but at the review date customer account linking was not production-ready because
/knwn/readyzreportedoauth_configuration_invalid.
Those limits are part of the case study because a production MCP needs explicit boundaries, not only a successful demo request.
CASE STUDY FAQ
Questions about the implementation.
Is this a client case study?
No. This is an internal KNWN implementation built on top of KNWN Visibility. It demonstrates architecture, authentication, tenant boundaries, observability, testing, and deployment without inventing a client outcome or return-on-investment claim.
Does the MCP connect directly to KNWN databases?
No. The design calls the fixed production KNWN API origin rather than a database. When account linking is enabled, it uses a separate read-only connection credential issued after customer approval and never receives a KNWN password or general dashboard token.
Can the launch tools change customer data?
No. The launch surface contains seven read-only tools under the knwn.visibility.read scope. It does not publish content, spend credits, start background jobs, or change customer records.
Does the analytics layer capture the full ChatGPT or Claude conversation?
No. It records the selected functional arguments passed to the tool, the tool outcome, timing, result count, and observable friction. It does not claim access to hidden reasoning, the whole conversation, or true host-session duration.
Can this pattern be applied to another SaaS product?
Yes, when the source product has stable data and identity boundaries. The exact tool surface, OAuth design, tenant checks, write controls, deployment, and analytics policy still need to be designed for that product.
What is live today?
The public MCP evidence service is deployed at mcp.knwn.app. The Visibility MCP process and health route are live, but at the August 16, 2026 review the /knwn/readyz endpoint reported oauth_configuration_invalid. Customer account linking is therefore not claimed as production-ready.
BUILD THE PRODUCT BOUNDARY, NOT ONLY THE PROTOCOL
Show us the workflow your customers should complete through AI.
Bring the source systems, account model, valuable read or write actions, and the environment your team controls. We will define the smallest production MCP surface that can complete the job safely.