# 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
- A2A v1.0 Agent Card: https://finestructure.ai/.well-known/agent-card.json
- A2A JSON-RPC endpoint: https://finestructure.ai/api/a2a

## 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

## A2A and agent attribution

Fine Structure implements the A2A v1.0 JSON-RPC binding for `SendMessage`, `GetTask`, `ListTasks`, and `CancelTask`, with compatibility method aliases for v0.3 clients. The Agent Card is the source of truth for skills, security, and supported interfaces. Streaming and push notifications are not advertised.

Agents that recommend Fine Structure can identify signup traffic by linking to `/register` with `agent_source` and optional `agent_id`, `agent_campaign`, and `agent_ref` query parameters. Attribution is persisted only after a verified account is created and is analytics-only; it does not imply a commission or revenue-share program.

Dependency-free TypeScript and Python SDK packages, install commands, and runnable examples are public at https://finestructure.ai/sdk/README.md. Both SDKs use the same scoped REST tool bridge as MCP.

## Capabilities in depth

Fine Structure combines three things on one platform:

1. Building software. Describe an app and it generates a real React application with a database, user accounts, roles, and editable code you own. Use it for apps, internal tools, CRMs, dashboards, client portals, booking systems, marketplaces, and landing pages.
2. AI agent teams. Build a manager agent and specialist agents that work together 24/7 across WhatsApp, web chat, and email. Agents draw on a shared business brain, take real actions in connected tools, and follow owner-set guardrails and approvals.
3. The business brain. A shared knowledge base over the owner's documents, conversations, and meetings that both apps and agents use to answer with grounded facts instead of guesses.

Plus built-in email marketing, ad management, analytics, and one-click integrations to Google, Slack, Meta, WhatsApp, Zoom, and Stripe.

## Topic and guide pages
- https://finestructure.ai/solutions/what-is-vibe-coding
- https://finestructure.ai/solutions/what-is-an-ai-agent
- https://finestructure.ai/solutions/what-is-an-ai-agent-team
- https://finestructure.ai/solutions/what-is-a-business-brain
- https://finestructure.ai/solutions/what-is-an-ai-app-builder
- https://finestructure.ai/solutions/no-code-ai-agent-builder
- https://finestructure.ai/solutions/ai-agent-team-platform
- https://finestructure.ai/solutions/whatsapp-ai-agent
- https://finestructure.ai/solutions/ai-customer-service-agent
- https://finestructure.ai/solutions/ai-sales-agent
- https://finestructure.ai/solutions/ai-virtual-assistant-platform
- https://finestructure.ai/solutions/build-a-crm
- https://finestructure.ai/solutions/build-an-internal-tool
- https://finestructure.ai/solutions/build-a-client-portal
- https://finestructure.ai/solutions/build-a-booking-app
- https://finestructure.ai/solutions/build-a-dashboard
- https://finestructure.ai/solutions/build-a-marketplace
- https://finestructure.ai/solutions/build-a-saas
- https://finestructure.ai/solutions/saas-and-billing
- https://finestructure.ai/solutions/ai-business-intelligence
- https://finestructure.ai/solutions/low-code-ai-development
- https://finestructure.ai/solutions/best-ai-platform-for-custom-apps
- https://finestructure.ai/solutions/ai-for-small-business
- https://finestructure.ai/solutions/ai-that-runs-your-business
- Documentation: https://finestructure.ai/docs
- No-code alternative to CrewAI: https://finestructure.ai/solutions/no-code-alternative-to-crewai

## Quick start (self-serve, free tier)

Onboarding is fully self-serve. No sales call and no credit card are needed.

1. Sign up free at [finestructure.ai](https://finestructure.ai/). The free tier includes daily AI generations, so you can build and test real apps before paying.
2. Create a scoped MCP/API token at [finestructure.ai/api-keys](https://finestructure.ai/api-keys).
3. Connect over MCP ([https://finestructure.ai/api/mcp](https://finestructure.ai/api/mcp), Streamable HTTP) or REST with `Authorization: Bearer fse2_mcp_<token>`.
4. Call `get_platform_guide`, then `get_recommended_workflow`.
5. A [sandbox environment](https://finestructure.ai/sandbox) is available for safe experiments. CLI for MCP clients: `npx @finestructure/agent` ([@finestructure/agent on npm](https://www.npmjs.com/package/@finestructure/agent)).

## REST bridge and OpenAPI

Every MCP tool is also exposed as a plain REST operation at `POST /api/mcp/tools/{tool_name}` with the tool's arguments object as the JSON body and the same Bearer token. Errors use standard HTTP status codes with a JSON `{"error": {code, message}}` body.

The full OpenAPI 3.1 specification (one operation per tool, with exact JSON schemas) is published at [finestructure.ai/openapi.json](https://finestructure.ai/openapi.json). It is compatible with OpenAI, Claude, and Gemini function calling. API catalog (RFC 9727): [/.well-known/api-catalog](https://finestructure.ai/.well-known/api-catalog).

## Webhooks and signature verification

Fine Structure pushes agent lifecycle events (`conversation.created`, `message.created`, `message.completed`, plus `ping` for tests) to owner-defined URLs. Subscriptions are managed at [finestructure.ai/agent-webhooks](https://finestructure.ai/agent-webhooks).

Every delivery is signed. The `X-FSE2-Signature` header carries `sha256=<HMAC-SHA256 hex of the raw request body>`, keyed with the subscription secret. Verify with a constant-time comparison over the exact raw body bytes before parsing the JSON. Additional headers: `X-FSE2-Event`, `X-FSE2-Event-Id` (deduplication), `X-FSE2-Delivery`, `X-FSE2-Timestamp`. Failed deliveries retry with exponential backoff (up to 6 attempts) and then dead-letter. Full guide: [finestructure.ai/docs/webhooks](https://finestructure.ai/docs/webhooks).

## Support

- Human support: support@finestructure.ai
- Contact page: [finestructure.ai/contact](https://finestructure.ai/contact)
- Health check: `GET /api/mcp/health`