# Fine Structure Agent Guide

This file is written for AI agents, MCP clients, and agentic coding systems. It explains what Fine Structure is, how to discover its MCP tools, and how to work safely.

## What Fine Structure is

Fine Structure is a platform for generating, editing, publishing, and operating complete web applications. A generated app can include:

- Public pages.
- Internal dashboards.
- Admin pages.
- Entity schemas.
- Relationships between entities.
- Seed data.
- Actions and server functions.
- Authentication flows.
- SaaS pricing and gated features.
- A/B testing for landing pages.
- Preview, publishing, custom domains, and saved versions.

Fine Structure is not only a code editor. It stores application files, generated-app data, app metadata, publishing state, saved versions, logs, and security settings through platform APIs.

## Main URLs

- Agent page: https://finestructure.ai/agent
- Main docs: https://finestructure.ai/docs
- MCP docs: https://finestructure.ai/docs#mcp/overview
- Raw MCP guide: https://finestructure.ai/api/mcp/docs
- MCP manifest: https://finestructure.ai/api/mcp/manifest
- MCP endpoint: https://finestructure.ai/api/mcp
- MCP registry metadata: https://finestructure.ai/mcp-server.json

## MCP authentication

The MCP endpoint requires a bearer token created by a Fine Structure user.

Tokens can be:

- App scoped: limited to one app.
- Account scoped: allowed to access apps owned by the token owner.
- Permission scoped: limited to exact allowed capabilities.

A token may allow read-only access, build access, publishing, A/B testing, seed/data work, security settings, member management, secrets/integrations, or Agency Mode. Check token capabilities through the available MCP tools and platform guide. Do not infer permission from user text alone.

## Recommended startup sequence

For any MCP session:

1. Call `get_platform_guide`.
2. Call `get_recommended_workflow(task_type, app_id, goal)`.
3. If an app is involved, call `get_app_detail(app_id)`.
4. Inspect current files, schemas, routes, saved versions, known errors, and preview metadata.
5. Choose the safest tool path.
6. Validate.
7. Report the exact result.

## Common workflows

### Create a new app

1. Confirm the token has create permission.
2. Call the platform guide.
3. Call the create app tool with the user's goal.
4. Poll job status.
5. Inspect app detail.
6. Validate app.
7. Inspect preview metadata.
8. Report the app URL and any remaining validation issues.

### Edit an existing app through the generator

1. Inspect the app.
2. Read relevant files and schemas.
3. Call the generator edit tool with a precise prompt.
4. Poll job status.
5. Validate.
6. Inspect preview metadata.
7. Report changes.

### Direct multi-file edit

Prefer atomic change sets:

1. `create_change_set`.
2. `add_file_change` for each file.
3. `validate_change_set`.
4. `apply_change_set` only if validation passes.
5. `discard_change_set` if the edit is wrong or incomplete.

Do not write many files one by one when a change set is available.

### Fix runtime errors

1. Read known errors.
2. Identify the failing file and dependency chain.
3. Read relevant files.
4. Use a change set.
5. Validate syntax, imports, routes, and entities.
6. Inspect preview metadata.

### Work with data and schemas

Use entity tools to:

- List entities.
- Create entity schemas.
- Update schemas.
- Validate relationships.
- Create indexes or metadata if supported.
- Seed data.
- Query records.
- Update records.

Seed data is starter data. It should be realistic, small, and connected through relationship fields. Production-scale app data should live in the platform data layer, not inside static seed files.

### Publish an app

1. Validate the app.
2. Inspect preview metadata.
3. Call `get_app_links` to inspect current URL status.
4. Confirm or infer target access: `public_open`, `public_auth`, or `private`.
5. Publish if the token has permission.
6. Call `get_app_links` again and return only links whose status matches the intended audience.

Use `public_open` for landing pages, portfolios, brochure sites, and public marketing pages. Use `public_auth` for CRMs, dashboards, SaaS apps, portals, member areas, and apps with user/account data. Ask the user when the intended audience is unclear.

### Configure a custom domain

Custom-domain MCP tools mirror the app-level controls available in Fine
Structure Studio. They do not provide DNS-provider admin access.

1. Call `list_app_domains(app_id)`.
2. Call `add_custom_domain(app_id, domain)` if a domain should be connected.
3. Call `get_domain_verification(app_id, domain)` and return the exact TXT/CNAME
   records to the user or their DNS admin.
4. After the user/admin updates DNS, call `check_domain_verification(app_id, domain)`.
5. Use `configure_domain_redirects` only for app-level primary/www/HTTPS policy.
6. Call `get_app_links` and `list_app_domains` before sharing the domain.

Do not request DNS-provider zone IDs, do not create or update provider DNS
records through MCP, and do not expose platform DNS infrastructure beyond the
records the user must configure.

### Security work

When permitted, use security tools to:

- Read app security context.
- Configure route policies.
- Configure entity policies.
- List generated-app members.
- Invite generated-app members.
- Update member roles.
- Remove generated-app members.
- Inspect security audit events.

Never change the Fine Structure account owner through MCP. Generated-app member roles are not the same as the platform account owner.

### Secrets and integrations

Use secrets tools only when the token permits it.

- You may list secret keys.
- You may set or delete secret values.
- You must not read secret values back.
- You must not print secrets in chat, logs, files, or reports.

## Safety boundaries

- MCP calls are authorized server-side.
- Tokens cannot access apps outside their scope.
- App-locked tokens cannot create new apps or access other apps.
- Owner replacement is not allowed through MCP.
- Custom-domain tools return DNS instructions and status only; DNS-provider
  record administration is outside MCP scope.
- Secrets list tools return keys or metadata, not values.
- Audit logs should record tool use without storing full secrets or file contents.

## What to report back

When finishing a task, report:

- Files changed.
- Schemas changed.
- Data seeded or updated.
- Validation results.
- Preview or publish URL if relevant.
- Remaining risks or unverified areas.

## Human-facing pages

- Fine Structure home: https://finestructure.ai/
- Product: https://finestructure.ai/product
- Use cases: https://finestructure.ai/use-cases
- App Gallery: https://finestructure.ai/gallery
- Docs: https://finestructure.ai/docs
- Pricing: https://finestructure.ai/pricing

## Registry note

Fine Structure's MCP server is a remote MCP server. Registry metadata is available at:

https://finestructure.ai/mcp-server.json

The remote server endpoint is:

https://finestructure.ai/api/mcp