The Architecture Behind My Agent-Readable Personal Hub

I rebuilt my personal hub as a three-layer system:

Website for humans.

API for software.

MCP for agents.

That sounds more complicated than a normal personal site, but the idea is simple. The same body of work should be readable through different interfaces depending on who, or what, is trying to understand it.

A human wants pages.

A script wants JSON.

An AI agent wants tools.

The architecture exists to serve all three without duplicating the content.

The human layer

The website is still the primary surface.

It has the pages people expect:

• homepage
• about
• products
• projects
• notes
• contact

This layer optimizes for trust, clarity, pacing, and visual hierarchy. It needs to answer human questions quickly:

• Who is this person?
• What has he built?
• What does he care about?
• Can I trust his judgment?
• What should I do next?

That is the job of the website.

But the website is not the source of truth. It is a rendered interface over structured content.

That distinction matters.

The API layer

The API layer exposes the same core content as structured JSON.

The important endpoints are:

GET /api/v1/me
GET /api/v1/projects
GET /api/v1/projects/:slug
GET /api/v1/products
GET /api/v1/products/:slug
GET /api/v1/notes
GET /api/v1/notes/:slug

This layer is for software that wants to read the personal hub without scraping the UI.

Examples:

• a dashboard
• a recruiter tool
• a search index
• a personal script
• an AI search system
• a future app that consumes my profile as data

The API returns predictable response envelopes with:

• api_version
• ai_summary
• meta
• data

The ai_summary field is intentional. Normal software can use the raw data. AI systems can use the summary to understand what the response means.

The MCP layer

The MCP layer exposes personal hub data as agent-callable tools.

Instead of asking an agent to decide which URL to fetch, the MCP server offers capabilities:

get_orlando_bio
get_projects
get_project
get_products
get_product
get_product_status
get_notes
get_note

This changes the interaction model.

An API exposes resources.

MCP exposes actions an agent can choose from.

That is why MCP fits AI assistants better than plain REST for certain workflows. The model can inspect the available tools, decide which one matches the task, call it with structured inputs, and use the result in its answer.

The data source layer

The content source is deliberately boring.

Projects, products, and notes live as structured content files. They have frontmatter for metadata and MDX bodies for long-form content.

That gives the system a clean split:

• frontmatter powers cards, filters, API responses, and MCP tool results
• MDX bodies power long-form pages
• localization fields support translated surfaces where needed
• slugs provide stable URLs and API identifiers

This is the part that keeps the architecture from becoming fragile.

I do not want one version of a project for the website, another version for the API, and another version for MCP.

One content model should feed every interface.

Validation

Structured content is only useful if the structure is reliable.

The site validates content fields like:

• title
• slug
• category
• excerpt
• published date
• project status
• product status
• screenshot path
• external links

This matters because the API and MCP layers amplify mistakes.

A broken slug is no longer only a broken page link. It can also become a broken API response, a bad agent tool result, or a confusing search artifact.

Validation keeps the content layer honest.

Error handling

The API uses explicit error envelopes for failure cases.

The goal is to make errors understandable to both software and humans:

• invalid input should return a validation error
• missing resources should return not found
• excessive requests should return rate-limit information
• unexpected failures should return a controlled internal error

Agents need this too.

If a tool call fails, the agent should know whether to retry, ask for a different slug, or explain that the requested resource does not exist.

Ambiguous failure is where agent workflows get messy.

Versioning

The API includes an api_version field.

Right now the version is simple: 1.0.0.

That field exists because public interfaces create expectations. Even a small personal API benefits from versioning once other tools might consume it.

If I change response shapes later, I want a clear path:

• preserve v1 for existing consumers
• add new fields without breaking old clients
• create v2 only when the contract changes meaningfully

Future-proofing is less about predicting everything and more about leaving yourself room to change without breaking trust.

Caching

Most personal hub data is read-heavy and changes slowly.

That makes it a good fit for caching.

The public API can safely cache profile, project, product, and note responses for short windows. Content changes do not need millisecond freshness. They need reliability and speed.

Caching also protects the system from unnecessary load if AI tools or crawlers start querying the same endpoints repeatedly.

That is one of the practical reasons to expose structured data instead of relying on page scraping.

The interface becomes easier to cache, reason about, and monitor.

Security boundaries

The most important architectural choice is the security boundary.

The public API and MCP tools should expose public personal hub context, not private operations.

For this system, that means:

• read-only MCP tools
• no destructive actions
• no draft content
• no secrets
• no admin-only data
• rate limits on public endpoints
• validation on every input

The rule is simple:

Do not give an agent more power than it needs.

For a personal hub, retrieval is enough.

The architecture in one line

The personal hub is not three separate systems.

It is one content system with three interfaces:

Content -> Website -> Humans
Content -> API -> Software
Content -> MCP -> Agents

That is the architecture I want more personal sites to move toward.

Not only prettier pages.

More structured surfaces.

More queryable work.

More websites that can be read by the tools people increasingly use to discover, evaluate, and remember people.