How I Would Build an Agent-Readable Personal Hub From Scratch

If I were building an agent-readable personal hub from scratch, I would not start with the homepage.

I would start with the data model.

The page matters, but the page is only one interface.

The goal is bigger:

Website: for humans
API: for software
MCP: for AI agents

To make that work, the site needs structured content before it needs visual polish.

Step 1: Define the entities

Start by deciding what your personal hub is actually made of.

For a developer personal site, I would use:

• profile
• projects
• products
• notes
• skills
• links
• tags
• tech stacks

Do not think about pages yet.

Think about objects.

A project is not a card. It is an entity.

A note is not a blog post page. It is an entity.

A product is not a marketing section. It is an entity.

That shift makes everything else easier.

Step 2: Choose the source of truth

The source of truth can be:

• MDX files
• JSON files
• a database
• a headless CMS
• a local content directory

For a personal site, I like MDX with frontmatter.

It gives you structured metadata and long-form writing in one place.

Example:

---
title: "ResistGate"
slug: "resistgate"
status: "active"
tags:
  - chrome-extension
  - productivity
tech_stack:
  - TypeScript
  - Chrome Extension Manifest V3
---

The frontmatter powers lists, filters, API responses, and MCP tool results.

The body powers the human-readable page.

Step 3: Design the public API

Once the content model exists, expose it through simple endpoints.

I would start with:

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

Keep the API boring.

Use predictable names.

Support filters people will actually use:

• tag
• status
• featured
• topic
• category
• limit
• offset
• locale

Do not over-design the first version.

Your goal is to make public context easy to fetch.

Step 4: Use a consistent response envelope

Every endpoint should return a predictable shape.

For collections:

{
  "api_version": "1.0.0",
  "ai_summary": "Found 3 active products.",
  "meta": {
    "total": 3,
    "returned": 3,
    "locale": "en",
    "generated_at": "2026-06-05T00:00:00.000Z"
  },
  "data": []
}

For single items, use the same pattern with one object in data.

This helps normal software and AI systems.

The software gets stable fields.

The model gets a summary of what came back.

Step 5: Add validation

Do not wait until the site has dozens of posts and projects to add validation.

Add it early.

Validate:

• required fields
• slug format
• valid categories
• valid statuses
• date format
• URL format
• array fields
• max lengths for metadata

Validation protects every interface.

A broken note should not silently become a broken page, broken API response, and broken MCP result.

Step 6: Add MCP tools

After the API exists, add MCP tools over the same content.

Good starting tools:

get_profile
get_projects
get_project
get_products
get_product
get_notes
get_note

Keep them read-only at first.

For a personal hub, read access is usually enough.

The agent should be able to answer:

• Who is this person?
• What have they built?
• What products have they shipped?
• What have they written about?
• Which projects match this topic?
• What work is active right now?

That gives agents useful context without giving them unnecessary power.

Step 7: Write strong tool descriptions

Tool descriptions are not decoration.

They are how the model decides when to call a tool.

Weak:

Gets projects.

Better:

Returns public projects from this personal hub. Use when the user asks what this person has built, wants examples by technology or tag, or needs project evidence for evaluation.

The description should explain:

• what the tool returns
• when to use it
• what inputs matter
• what boundaries exist

If the model cannot understand the tool, the tool might as well not exist.

Step 8: Add docs

Create one permanent page:

/api

or:

/developers

That page should include:

• API overview
• endpoint list
• response examples
• MCP overview
• tool list
• example prompts
• rate limits
• attribution notes
• security boundaries

The posts create distribution.

The docs page creates durable proof.

Step 9: Add examples

Examples make the system real.

For the API:

GET /api/v1/projects?tag=ai
GET /api/v1/products?featured=true
GET /api/v1/notes?topic=agents

For MCP:

Summarize active products from this personal hub.

Find projects that demonstrate TypeScript and AI product experience.

Create a recruiter brief from the profile, products, and projects on this personal hub.

Examples help humans understand what the system is for.

They also help agents produce better outputs.

Step 10: Keep the security boundary small

Do not start by giving agents write access.

Do not expose admin data.

Do not include drafts.

Do not return secrets, analytics, billing records, or private contact data.

Start with public, read-only context.

That is enough to make the personal hub agent-readable without making it risky.

The build order

If I had to compress the whole process, I would build it in this order:

1. Define entities
2. Create structured content
3. Validate content
4. Render human pages
5. Expose REST endpoints
6. Add MCP tools
7. Write docs
8. Add examples and demos

Most people start with the page.

I would start with the model.

The page is one output.

The API is another.

The MCP server is another.

That is how a personal hub becomes future-proof: not by adding AI words to the homepage, but by making the work structured enough for humans, software, and agents to understand.