Amaphupho WebMCP

Culturally grounded African dream insight that AI agents can safely invoke on the open web.

Comment

Inspiration

Amaphupho started from a simple problem: general purpose AI can be useful for reflection, but it should not automatically become the authority on every cultural domain.

Dream interpretation is deeply contextual, and African dream traditions carry meanings that are often flattened, generalised, or completely missed by mainstream AI systems.

I built Amaphupho as a culturally grounded African dream interpretation platform, drawing on Southern African traditions including Zulu, Xhosa, and Sotho perspectives.

When the WebMCP Challenge launched, it introduced a new way for me to think about how a specialist website like Amaphupho could work with general purpose AI agents.

The idea that shaped the project was:

The agent knows the person through their conversation. Amaphupho knows the specialist cultural domain. WebMCP lets them work together.

Instead of an agent scraping the site, guessing how the interface works, or reproducing Amaphupho's cultural knowledge inside another model, I can explicitly expose the capabilities I want an agent to use.

What it does

Amaphupho WebMCP exposes three structured tools to compatible AI agents.

search_dream_symbols allows an agent to search Amaphupho's African dream symbol glossary. It is public, read only, and does not consume a user credit.

interpret_dream allows a signed in user to ask their agent to interpret a dream using Amaphupho. The tool uses the same production interpretation path as the normal application, so the existing authentication, credit, rate limit, and journal persistence rules still apply.

search_dream_journal allows a signed in user to search their own private dream history through an agent. It is read only and explicitly restricted to the currently authenticated Supabase user.

A typical interaction could be:

  1. A user asks their agent what a snake means in Amaphupho's cultural glossary.
  2. The agent calls Amaphupho's public symbol tool.
  3. The user shares a complete dream and asks Amaphupho to interpret it.
  4. The interpretation is generated through the existing production service and saved to the user's private journal.
  5. Later, the user can ask their agent to find recurring themes in their own dream history.

The website still works normally in browsers that do not support WebMCP.

How I built it

I implemented the WebMCP extension in TypeScript using the WebMCP imperative API.

Amaphupho registers tools through:

document.modelContext.registerTool()

I gave each tool a clear name, description, input schema, annotations, and execution function.

The main architectural decision I made was to avoid creating a separate "agent backend".

The interpret_dream tool calls the existing Amaphupho production interpretation service. That means agent initiated interpretations use the same authentication checks, credit accounting, rate limiting, Gemini integration, and Supabase persistence as interpretations started through the normal user interface.

The symbol search tool reads from Amaphupho's curated cultural symbol data and returns structured results.

The private journal tool queries Supabase using the currently authenticated session and explicitly filters results by that user's ID.

I designed the integration as progressive enhancement. If WebMCP is not available in the browser, Amaphupho continues to operate as a normal web application.

I also added Playwright browser tests, conversational eval cases, tool annotations, provenance documentation, GitHub Actions verification, and automated checks for repository formatting requirements.

The live application is hosted through Netlify and served from Amaphupho's own domain at https://www.amaphupho.co.za.

Challenges I ran into

One of the biggest challenges was deciding what not to expose.

It would have been easy for me to create a broad agent endpoint that could perform many application actions, but that would also create a much larger privacy and security surface.

Instead, I deliberately kept the WebMCP layer small.

The public cultural search tool does not require authentication.

Dream interpretation requires authentication and has a real side effect because it consumes a credit and saves an entry.

Journal search requires authentication but remains strictly read only.

Another challenge was making agent initiated behaviour match the existing product instead of creating a parallel implementation. Reusing the production interpretation service meant dealing carefully with sessions, credits, rate limits, failures, and journal persistence.

Amaphupho also existed before the challenge, so another important challenge was making the new work independently reviewable. I therefore documented the pre WebMCP boundary and the new WebMCP extension separately in the public challenge repository.

Finally, private dream journals contain personal information, so I designed the journal tool so that an agent can never provide an arbitrary user ID or search another person's data.

Accomplishments that I'm proud of

I'm proud that the WebMCP integration is running inside a real production application rather than a standalone demonstration.

I designed the three tools with different access and side effect boundaries that match what they actually do.

Agent initiated dream interpretation reuses Amaphupho's existing production path instead of bypassing product rules.

Private journal access is scoped to the authenticated user and remains read only.

The site still works normally without WebMCP support.

I also added automated browser verification and eval cases rather than relying only on manual demonstrations.

Most importantly, I think the integration demonstrates a model where a general purpose agent does not need to own every specialist capability.

Amaphupho remains responsible for its cultural knowledge, its user data, and its application rules, while the agent provides the conversational interface.

What I learned

The biggest lesson I learned was that building for agents is not mainly about exposing more functionality.

It is about exposing the right functionality with clear boundaries.

Tool names and descriptions matter because the agent needs to understand when a capability should be used.

Input schemas matter because they make the interaction predictable.

Annotations matter because read only actions should be distinguishable from actions with side effects.

Authentication boundaries matter because an agent should not gain broader access simply because it is acting on behalf of a user.

I also learned that WebMCP can create a useful relationship between general purpose agents and specialist websites.

A general purpose agent can retain conversational context and understand what the user is trying to achieve, while a specialist service can remain authoritative for its own domain.

That feels more sustainable to me than requiring every agent to replicate every specialist service internally.

What's next for Amaphupho WebMCP

The next step I want to explore is deeper longitudinal dream analysis with explicit user control.

A user could ask Amaphupho to identify recurring themes across a selected period of their journal, compare repeated symbols, or explore how certain themes have changed over time.

I also want to expand multilingual support across English, isiZulu, and Sesotho so users can interact with both the agent and Amaphupho in the language that is most meaningful to them.

Future WebMCP tools could support richer cultural symbol exploration and guided reflection without exposing unrestricted access to private journal data.

More broadly, I see Amaphupho as an example of how culturally specific and specialist web applications can participate in the agentic web while remaining responsible for their own knowledge, permissions, and user trust.

Built With

  • african-languages
  • ai-agents
  • authentication
  • chrome-devtools
  • cultural-technology
  • github-actions
  • google-gemini
  • netlify
  • netlify-functions
  • playwright
  • postgresql
  • progressive-enhancement
  • react
  • row-level-security
  • serverless
  • supabase
  • typescript
  • vite
  • web-apis
  • webmcp
Share this project:

Updates

Submission history