Building for AI interfaces isn't an API problem...It's a product design problem.
That's the main thing we walked away with after shipping the Docket ChatGPT app and it reshaped almost every technical decision we made along the way.
If we could go back in time, here's what we'd tell ourselves on day one.
1. Tool naming and descriptions are everything
Make tool names flat-out obvious. No ambiguity, no cleverness.
The tool description is the only real lever you have to steer model behavior. MCP server-level instructions? We found them largely useless. All meaningful prompting happened at the tool description level — what triggers the tool, and how the retrieved information should be presented back to the user.
If you're not treating your tool descriptions like product copy, you're leaving a lot on the table.
2. Think product surface, not API dump
This is the most important mindset shift we made.
APIs are designed for developer consumption. A ChatGPT app tool is a product surface. When a user asks a question, they shouldn't get an API dump — they should get clean, concise, high-intent information. That often means combining multiple internal calls (auth, search, fetch) into a single, clean request-response surface.
Build it from the product perspective.
Not the developer perspective.
3. URL length will break your links
If your tools return file URLs, this will bite you.
Enterprise file URLs, especially AWS pre-signed URLs, can be extremely long, and you have no control over which model your end user is running. Smaller models corrupt long strings constantly. We saw broken links in nearly every session during early development.
The fix: a dedicated URL shortener so every URL passed to the agent is as short as possible. We built one internally using AWS routing to avoid adding latency from an external service. It sounds like a minor detail. It isn't.
4. Authentication and user-scoped access control
Security and role-based access control aren't optional for enterprise products.
We evaluated two approaches. Encoding a token in the base URL looked simple at first — but it created security exposure, and FastMCP doesn't support path variables out of the box, so that approach was a dead end for us anyway. We landed on WorkOS, which solved both problems cleanly.
If you're building for enterprise, solve auth before you solve anything else.
5. Give your ChatGPT app its own dedicated MCP server
Once you publish a ChatGPT app, every change goes back through the review cycle. That gets expensive fast if you're sharing an MCP server with other surfaces you're actively iterating on.
Keep them separate. One MCP for your ChatGPT app, another for Claude or wherever else. Tool descriptions often need to differ per surface anyway.
Think of your core functionality as an internal library, each MCP server is just a thin, tailored packaging layer on top of it.
6. A visual UI is not required
We didn't build a visual UI element into our ChatGPT app, and we expected that to hurt us in review. It didn't.
A simple, well-polished experience that makes sense as a product surface is enough.
Don't let the absence of a UI become a reason to delay shipping.
7. Use the metadata and type hints ChatGPT exposes
Don't skip this step.
Type hints are especially important — they signal to ChatGPT that your tool only needs read access to external systems, which means users won't get hit with permission prompts on every interaction.
The invoking/invoked message metatags matter more if you're building a full UI experience; for non-UI apps like ours, they're less critical.
8. Getting through the review process
The review process takes time. What accelerated ours was reaching out through our Mayfield contact, who connected us to our OpenAI account manager. They were able to fast-track review significantly.
If you have a relationship with OpenAI, or someone who does, use it early, not after you've been waiting two weeks.
9. Resources and gotchas
OpenAI's documentation is solid for overall design. FastMCP is a great starting point and works out of the box for most things.
Two areas that are under-documented and required custom work: adding meta tags in FastMCP, and adding the verification token in your application. Budget extra time for both.
The through-line across all of this: every time we thought about what we were building as an API, we made the wrong call. Every time we thought about it as a product, we made the right one.
Build accordingly.