THE DEVELOPER FIELD GUIDE
Build with context.
Ship with confidence.
104 practical guides for connecting your agent, designing your data, and shipping an app with clear access rules. Each guide includes a concrete example and a boundary to verify.
Connecting your first backend? Start with the foundations → Connect your agent →
104 guides to help you investigate
Which MCPBackend endpoint should your agent connect to?
The coding agent connects to the remote MCP endpoint, while the application connects to the data API.
Read the guide →MCP & agent workflowsStreamable HTTP or stdio for MCPBackend?
MCPBackend is a hosted Streamable HTTP MCP service, so the client connects to a URL rather than launching a local server process.
Read the guide →MCP & agent workflowsMCP connects, but backend tools are not visible
A connection indicator does not prove that tool discovery completed or that the client enabled the returned tools.
Read the guide →MCP & agent workflowsMCP OAuth keeps returning to consent
A repeated consent flow can indicate a mismatch between the client's registered callback, stored connection state or selected account.
Read the guide →MCP & agent workflowsMCP returns unauthorized after a successful connection
An MCP authorization error concerns the agent's account connection, not automatically your app's API key or end-user login.
Read the guide →MCP & agent workflowsYour agent is changing the wrong project
Project identity needs to be explicit before a coding agent makes backend changes.
Read the guide →MCP & agent workflowsHave an agent inspect the schema before creating tables
An existing backend should be inspected before an agent creates new tables or columns.
Read the guide →MCP & agent workflowsUse get_project_api instead of guessing REST routes
The generated project contract is the source for the routes and schema an agent should use.
Read the guide →MCP & agent workflowsVerify an agent's backend change after the tool returns
A successful tool response is one part of verification, not proof that the full feature works.
Read the guide →MCP & agent workflowsAgent Skill versus MCP server: what each contributes
An Agent Skill provides workflow instructions, while the MCP server supplies authenticated tools.
Read the guide →MCP & agent workflowsAn MCP mutation timed out: inspect before retrying
A timed-out tool call may have completed on the server even if the client did not receive its response.
Read the guide →MCP & agent workflowsAn agent created an API key: handle the one-time secret
Creating an API key returns sensitive material that should be stored for the intended server integration.
Read the guide →MCP & agent workflowsLimit an agent workflow to the intended team projects
An agent's useful reach depends on the connected account's project permissions.
Read the guide →Schema designChoose a primary key before wiring record URLs
The primary key determines how an individual record is addressed through the generated API.
Read the guide →Schema designCreate parent records before dependent records
A foreign-key relationship makes the existence of a referenced parent part of data validity.
Read the guide →Schema designReview cascading deletes before enabling them
A cascading relationship can remove dependent rows when a parent is deleted.
Read the guide →Schema designRequired or nullable: choose the empty-state contract
A nullable column and a required column encode different guarantees for every API caller.
Read the guide →Schema designAdd a required column to a table with existing rows
A new required column needs a value for rows that already exist.
Read the guide →Schema designUse a unique field without confusing it with validation
A unique constraint prevents duplicate stored values according to the database's comparison behavior.
Read the guide →Schema designStore money with an explicit unit and currency
Money fields need a unit and currency contract, not just a numeric type.
Read the guide →Schema designKeep timestamp formats and timezones consistent
Timestamp text needs a consistent format if the application relies on sorting and comparison.
Read the guide →Schema designJSON column or related table for nested data?
A JSON field is useful for flexible payloads, while related tables make frequently queried relationships more explicit.
Read the guide →Schema designBoolean fields: agree on the stored representation
MCPBackend's boolean schema type uses SQLite integer storage, so clients need a consistent representation at the API boundary.
Read the guide →Schema designPlan indexes around real filters and sorting
An index should serve a query the application actually performs.
Read the guide →Schema designRenaming a column can break generated clients
A schema rename changes the field and filter names that API callers use.
Read the guide →Schema designWhy tables starting with an underscore are reserved
MCPBackend reserves underscore-prefixed tables for internal data such as application users.
Read the guide →REST API integrationMake your first MCPBackend REST request
A first request should verify the actual project URL, table name and caller type with the smallest useful read.
Read the guide →REST API integrationFetch resolved, but the API returned an error
A fetch promise can resolve for an HTTP error response.
Read the guide →REST API integrationA 400 error names an unknown column
Unknown-column errors often indicate a mismatch between deployed client code and the current table schema.
Read the guide →REST API integrationUse supported REST filter operators
MCPBackend filter syntax supports defined operators rather than arbitrary SQL expressions.
Read the guide →REST API integrationMultiple REST filters combine with AND
Multiple supported filters narrow a result together rather than automatically creating an OR expression.
Read the guide →REST API integrationUnderstand contains search before using LIKE filters
A contains-style filter is different from a full-text search engine.
Read the guide →REST API integrationOffset pagination can shift when records change
Offset pagination selects a position in the current ordered result.
Read the guide →REST API integrationResponse count is not always the full table total
A returned count must be interpreted according to the API's response contract.
Read the guide →REST API integrationPATCH changes selected fields rather than replacing a row
A partial update sends only the fields being changed.
Read the guide →REST API integrationA successful DELETE returns no JSON body
A 204 response indicates successful completion without a response body.
Read the guide →REST API integrationA record returns 404: missing or not owned?
A 404 can represent a missing record or a record outside the end user's owner scope.
Read the guide →REST API integrationDistinguish 402 write caps from 429 request caps
MCPBackend quota errors identify different capacity boundaries.
Read the guide →REST API integrationA create request lost its response: avoid duplicate rows
A lost response does not establish whether a create request reached the server.
Read the guide →Permissions & row accessWhy an API key can see rows hidden from users
Machine API keys bypass end-user row policies and use their own table permissions.
Read the guide →Permissions & row accessA table without a row policy denies end-user access
A missing policy is not the same as public access.
Read the guide →Permissions & row accessPublic reads and owner writes need a clear content model
Public-read and owner-write policies suit content that anyone may view but only its author should change.
Read the guide →Permissions & row accessAuthenticated access is broader than owner access
Authenticated mode allows any signed-in user of the project to perform the permitted table operation.
Read the guide →Permissions & row accessOwner IDs are assigned from the authenticated caller
On owner-mode creation, ownership comes from the calling user's identity rather than a client-selected owner field.
Read the guide →Permissions & row accessUse a custom owner column consistently
A custom owner column must match the table's policy and the data model.
Read the guide →Permissions & row accessTest owner isolation with two real app users
A two-user test checks the boundary that a single happy-path session cannot.
Read the guide →Permissions & row accessPlan a public form without publishing submissions
A public submission form needs write access without exposing its collected records.
Read the guide →Permissions & row accessUse a create-only key for a server-side integration
A server job that only inserts records does not need broad read, update or delete privileges.
Read the guide →Permissions & row accessAn API key belongs to a different project
A machine key is bound to its project, so using it with another project's URL should fail even when the tables share names.
Read the guide →Permissions & row accessFrontend filtering is not an access-control boundary
A hidden row in the UI can remain accessible through a direct API request.
Read the guide →Permissions & row accessOwner policies are not organization membership rules
A single-owner policy does not express arbitrary team membership or organization roles.
Read the guide →Permissions & row accessRevoking a key and verifying that access stops
Key revocation should be followed by a test through the actual data path.
Read the guide →Application authenticationDashboard login and app-user login are separate
The developer dashboard account manages projects, while app-user authentication identifies people using the application you build.
Read the guide →Application authenticationApp signup fails because authentication is disabled
End-user authentication is enabled per project, so a valid-looking signup request can fail when that project has auth disabled.
Read the guide →Application authenticationHandle an email_taken response during signup
An email_taken response means the signup address already exists in that project's user store.
Read the guide →Application authenticationDiagnose invalid credentials without exposing passwords
An invalid_credentials response identifies a failed login, not a reason to log the submitted password.
Read the guide →Application authenticationVerify the current user before loading private data
A stored token and a visible user name do not prove the current API session is valid.
Read the guide →Application authenticationPlan around MCPBackend's non-expiring app-user tokens
Current MCPBackend app-user tokens do not expire automatically.
Read the guide →Application authenticationWhat local logout does and does not do
Local logout removes a session from the current client, but it is not the same as server-side token revocation.
Read the guide →Application authenticationA user token is rejected by another project
App-user tokens are scoped to the project that issued them.
Read the guide →Application authenticationCreate a profile table without exposing authentication storage
Application profile fields belong in a separate model from password and login storage.
Read the guide →Application authenticationPlan account recovery before choosing an auth flow
Password reset is an application requirement that must be checked against the current authentication feature set.
Read the guide →Application authenticationAvoid racing private requests against session restoration
A private-data request can run before the app has restored and validated its session.
Read the guide →Application authenticationClear private cached data when users switch accounts
A frontend cache can display the previous user's records after the backend correctly changes identity.
Read the guide →Application authenticationWhy users sign in again after self-hosting an export
The exported runtime uses a new JWT secret, so hosted user tokens are not a session migration mechanism.
Read the guide →Webhooks & eventsVerify webhook signatures using the raw body
A webhook signature authenticates the exact request bytes used by the sender.
Read the guide →Webhooks & eventsCheck signature length before a timing-safe comparison
A timing-safe comparison routine may require equal-length inputs.
Read the guide →Webhooks & eventsA webhook signature fails with the wrong secret
Each webhook signing configuration needs the corresponding receiver secret.
Read the guide →Webhooks & eventsKeep webhook handling within the delivery timeout
MCPBackend's current webhook attempt has a five-second timeout.
Read the guide →Webhooks & eventsMCPBackend webhooks do not automatically retry
Current webhook delivery makes one attempt without automatic retries.
Read the guide →Webhooks & eventsDeduplicate webhook processing by event identity
A receiver should avoid repeating an action if the same event is presented more than once.
Read the guide →Webhooks & eventsWebhook arrival order is not record-update order
Webhooks do not guarantee arrival ordering, so the last notification received may not describe the latest record state.
Read the guide →Webhooks & eventsChoose webhook patterns that match the intended operation
Webhook subscriptions match table-and-operation event names.
Read the guide →Webhooks & eventsA new webhook is not active immediately
Webhook configuration is cached briefly at the edge, so a newly created or disabled subscription can take time to be observed.
Read the guide →Webhooks & eventsReconcile webhook consumers against the data API
A reconciliation routine compares the consumer's stored state with the authoritative backend.
Read the guide →Webhooks & eventsHandle deletion events without assuming a later fetch succeeds
After a deletion, a follow-up record fetch may correctly return not found.
Read the guide →Webhooks & eventsRotate a webhook secret with a receiver transition plan
A webhook secret change requires coordination between the emitting subscription and the receiver configuration.
Read the guide →Webhooks & eventsPrevent a webhook consumer from creating an event loop
A consumer that writes back to the same subscribed table can trigger another notification.
Read the guide →Launch & operationsCheck backend readiness before an app launch
A launch review should exercise the intended workload and access boundaries, not just confirm that the homepage loads.
Read the guide →Launch & operationsEstimate API requests from user behavior
API request volume follows application behavior, including polling and retries, rather than user count alone.
Read the guide →Launch & operationsEstimate writes separately from API request volume
Write usage and request volume measure different work.
Read the guide →Launch & operationsEstimate storage growth before keeping every event forever
Storage capacity depends on retained records, payload sizes and indexes.
Read the guide →Launch & operationsDesign a useful UI for quota failures
Quota failures need a clear application state so users do not keep submitting an operation that cannot currently succeed.
Read the guide →Launch & operationsKeep staging and production project configuration separate
Separate projects reduce accidental overlap only when URLs, keys and user sessions stay paired with the intended environment.
Read the guide →Launch & operationsRelease a schema change with client compatibility in mind
A schema change and a client deployment may not reach every user at the same time.
Read the guide →Launch & operationsRehearse an Eject export before you need it
An export becomes an operational exit path only after you have restored and tested it.
Read the guide →Launch & operationsAn export download link expired
The database export uses a short-lived authenticated download, so an old link may stop working without indicating that the project data is gone.
Read the guide →Launch & operationsReplace hosted API keys when moving to self-hosting
Hosted machine keys are not exported as reusable secrets.
Read the guide →Launch & operationsKeep the self-hosted SQLite database on a persistent volume
A running container is not a durable storage plan by itself.
Read the guide →Launch & operationsHand off a backend with more than a dashboard link
A useful handoff explains the model, access boundaries, integrations and operating limits.
Read the guide →Launch & operationsCapture useful evidence for a backend incident
A precise incident report links failed requests to project identity, caller type and time without leaking credentials.
Read the guide →App blueprintsBuild a private notes app with owner-scoped records
A private notes app is a focused starting point for end-user auth and owner-based access.
Read the guide →App blueprintsBuild a public directory with controlled publishing
A public directory needs readable listings and a trusted publishing workflow.
Read the guide →App blueprintsPlan an internal inventory tool with trusted server access
An inventory tool can use structured records for items and locations, but stock changes need a deliberate consistency and permission model.
Read the guide →App blueprintsBuild a habit tracker with separate habits and check-ins
A habit tracker benefits from separate habit definitions and dated check-in records.
Read the guide →App blueprintsBuild a recipe book with a clear ingredient model
A recipe book can start with private recipes and expand into related ingredient rows when the app needs structured editing.
Read the guide →App blueprintsBuild a lead intake form without exposing the lead list
A lead form is a write-oriented public workflow paired with private review.
Read the guide →App blueprintsPlan a feedback board with private submissions and public posts
A feedback board often has two audiences: people submitting ideas and people browsing approved posts.
Read the guide →App blueprintsBuild a personal bookmark manager with explicit URL handling
A bookmark manager is a useful owner-scoped CRUD app with a few important input rules.
Read the guide →App blueprintsBuild a job application tracker around user-owned stages
A job tracker can model applications as private records with a small status vocabulary.
Read the guide →App blueprintsPlan event RSVPs without confusing public event data and attendee data
An RSVP app has public event information and potentially private attendee details.
Read the guide →App blueprintsBuild a reading list with user-specific progress
A reading list needs to distinguish shared book metadata from each user's private progress.
Read the guide →App blueprintsPlan a client project tracker with an explicit membership layer
A client project tracker usually needs several people to access the same workspace.
Read the guide →App blueprintsBuild a content calendar with a separate publishing workflow
A content calendar stores plans and status, while publishing to external channels is another workflow.
Read the guide →