How to expose an internal system as an MCP tool

What matters here

• Scope the tool to a job, not an API. One tool per intent limits what a misread instruction can do.
• Resolve identity per call. An agent acting as a shared service account is an audit trail that names nobody.
• Make every write idempotent. Models retry, and a retried create is a duplicate record somebody has to clean up.
• Return errors a model can act on. "Failed" produces a retry loop; "missing required field: close date" produces a fix.
• Log arguments and results, not just that the tool was called. Reconstructing what an agent did is the whole point.

Who this is for

You run platform engineering or AI operations. Teams want agents that can act on internal systems, and the current options are a broad credential or nothing.

How it works in practice

The path from an agent deciding to act to the action being safe to allow.

1. 1

   The tool is defined as one job

   Create an opportunity, not access Salesforce. Scope is the primary control.

2. 2

   The caller identity is resolved on every call

   The agent acts as the person who asked, with their permissions, not as a service account.

3. 3

   Arguments are validated against a typed schema

   Before anything is attempted, so a malformed call fails cleanly instead of half-executing.

4. 4

   Writes carry an idempotency key

   Derived from the arguments, so a model retrying does not create a second record.

5. 5

   Errors come back describing the fix

   Structured and specific, because a model can act on a reason and cannot act on failure.

6. 6

   Every invocation is logged in full

   Who, what tool, what arguments, what result. That log is the reason this is allowed at all.

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

1. 1

   Set up and scope the tool to a job

   Scope is the primary control, and it is decided before any code.

   Headless skills build-workflow

   Copy

   Use build-workflow. The systems in play are Salesforce, or whatever we
   run in those seats.
   
   Do not build a tool that wraps the API. Build one tool per job, and help
   me name them:
   
     create_opportunity, with account, name, amount, close date and stage
     update_opportunity_stage, with an id and a stage
     find_account, with a name or domain, read only
   
   Each takes the narrowest arguments that do the job and nothing more.
   
   A single salesforce_query tool gives an agent everything the credential
   can reach, and the blast radius of one misread instruction becomes the
   whole CRM. Narrow tools are the control, and everything else here is
   secondary to that.

   Naming the tools is the design. If a tool name needs the word "and" in it, it is two tools.

2. 2

   Resolve identity on every call

   An agent acting as a service account is an audit trail that names nobody.

   Headless skills build-workflow

   Copy

   Use build-workflow. Every invocation resolves the calling identity and acts
   with that person's permissions.
   
   Take the caller from the authenticated session rather than from an
   argument, because an argument can be supplied by the model and an
   authenticated session cannot.
   
   Apply their real permissions. If the person cannot edit that opportunity
   in the CRM, the agent acting on their behalf cannot either. An agent
   should never be able to do more than the person asking.
   
   Never use a shared service account with broad rights. It is easier and it
   produces an audit log that says a robot did it, which is exactly the
   answer nobody can accept.

3. 3

   Type the arguments, and make writes idempotent

   Because models retry, and a retried create is a duplicate.

   Headless skills tray-patterns

   Copy

   Define a strict schema per tool: required fields, types, enums for
   anything the target system constrains, and sensible bounds.
   
   Validate before attempting anything, so a malformed call fails cleanly
   rather than half-executing and leaving a partial record.
   
   Then make every write idempotent. Derive a key from the arguments and the
   caller, check it before writing, and return the existing result if the
   same call arrives twice.
   
   Models retry on timeouts, on ambiguous responses, and sometimes because
   they simply decide to. Without idempotency that is a duplicate
   opportunity, and somebody finds it at the end of the quarter.

4. 4

   Return errors a model can act on

   "Failed" produces a retry loop. A reason produces a fix.

   Headless skills tray-gotchas tray-patterns

   Copy

   Use tray-gotchas, then design the error responses deliberately.
   
   Return structured errors that name the problem and the fix: missing
   required field and which one, invalid enum value and the accepted list,
   permission denied and on what, record not found and what was searched
   for.
   
   Never return a bare failure. A model given "failed" retries the identical
   call, often several times, and then reports success to the user because
   the last attempt returned something.
   
   Distinguish retryable from terminal. A rate limit is retryable. A
   permission denial is not, and a model retrying it looks exactly like an
   attack in your logs.

5. 5

   Log everything, and set a budget

   The log is the reason this is allowed at all.

   Headless skills tray-patterns

   Copy

   Log every invocation: who called, which tool, the full arguments, the
   result, the latency, and whether it succeeded.
   
   That log is the entire reason exposing internal systems to an agent is
   acceptable. Without it the honest answer to what did the agent do is
   nobody knows.
   
   Then add limits: a per-caller rate limit, a daily budget for expensive
   tools, and an approval step for anything above a threshold, such as
   creating an opportunity above a value or writing to more than a handful
   of records at once.
   
   Report per tool: invocations, error rate by type, retries after an error,
   and calls that hit a limit. A tool with a high retry rate usually has a
   bad error message, not a bad caller.

6. 6

   Check it end to end, then hand the scopes to platform

   Because which tools exist is a governance decision.

   Copy

   Run the per-step schema checks and the whole-workflow audit before this
   touches production. Test with a deliberately confused instruction and
   confirm the tool refuses, not improvises.
   
   Then open the same workflow in Tray Build so platform engineering can add
   tools, adjust scopes and change approval thresholds in the visual canvas.
   Which tools exist and what they may do is a governance decision, and it
   should be visible to somebody who does not read code.

What it connects to

The agent calls the tool, the tool acts on a system, and the identity comes from neither.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Questions people ask

Further reading

Background on the same subject, for the case rather than the build.

• MCP governance in the enterprise
• Flying blind: Why MCP needs its API management moment

Related guides