Claude Code integration

The TechAppForce plugin for Claude Code connects to the same gateway as Studio, and adds skills for building apps, entities, screens and permissions, plus troubleshooting and tool reference.

What the gateway is

TechAppForce apps are metadata: rows that describe entities, fields, queries, screens and the rest. The gateway is an MCP (Model Context Protocol) server that turns platform operations into tools an AI assistant can call: finding what exists, reading records, creating entities and screens, granting access, adding menu items, registering lifecycles and workflows, and diagnosing problems. It stores nothing itself. Every tool reads from or writes to the real TechAppForce services.

The gateway also serves the TechAppForce knowledge base, so a client can look up exact component, configuration and enum shapes instead of guessing them.

Connect a client

You need two things from your TechAppForce administrator: the gateway URL and your personal API key. The key is tied to your TechAppForce user and your default tenant, app and environment. Keep it in your client's user configuration, never in a repository.

The gateway speaks MCP over streamable HTTP. For Claude Code, register it with your key:

claude mcp add --transport http taf <GATEWAY-URL>/mcp \
  --header "Authorization: Bearer <YOUR-KEY>"

Then run /mcp in Claude Code to confirm the server is connected. For Cursor, Codex or another MCP client, add a remote MCP server in that client's settings with the same URL and an Authorization: Bearer header carrying your key.

• TAF Studio connects to the gateway for you, using your Studio sign-in and the app you have selected. Change the app in Studio and the gateway follows it.
• The TAFI pipeline runs against the gateway with writes applied directly, because nobody is there to approve each call. Its approval gates sit earlier, at requirements, data model and plan. See The build flow.

Check who you are first

Ask the assistant to run taf_whoami before anything else. It returns your user, tenant, app, environment and the app's roles. If any of those is wrong, stop: every write lands in that app. taf_health tells an authentication problem apart from a network or service problem.

Previews and confirm

Every tool that changes something follows the same pattern: preview, confirm, apply, read back.

• Dry run. Calling a write tool with dry_run=true shows exactly what would be written and writes nothing. It is available on every write tool.
• Preview by default. For interactive clients, a write called without confirm=true returns a preview naming the target app, and writes nothing.
• Confirm. The assistant sends confirm=true only after you approve the preview. Read the target app in the preview before you approve it.
• Read back. A read tool re-reads what was written to prove the change landed.

Reading results

Write tools return the real id of what they created, plus a status:

• created: written and visible now.
• exists: something with that name already exists; its id is returned and nothing new is written, so most build tools are safe to repeat.
• preview: nothing was written. Review it, then call again with confirm=true.
• pending: accepted but not visible yet. Confirm with a read instead of repeating the write. Workflow and notification tools can return this where the matching platform service is not deployed; that is an honest answer, not a fault to retry.

Rules the gateway enforces

The gateway gives the same instructions to every client, so the knowledge needed to use the tools correctly lives on the server rather than in each client's prompt:

• Never invent an id. Every id must come from an earlier tool result.
• An empty read can mean the caller has no read grant, not that there are no rows. Check permissions before deciding a write failed.
• For exact component or configuration shapes, search the knowledge base first and build from it.
• Compile-check any C# hook before saving it. A hook that fails to compile breaks saves on its entity.

Troubleshooting

• “Invalid or missing API key”. Check the Authorization: Bearer header in your client configuration.
• The build landed in the wrong app. Run taf_whoami. In Studio, check the selected app.
• Reads come back empty, or writes seem to do nothing. taf_diagnose_feature checks the entity, your roles and grants, and its screens in one call.
• An error you do not understand. Pass the whole message to taf_explain_error for the likely cause and fix.