Tool Execution

Overview

When an LLM returns tool calls in its response, DeepIntShield does not automatically execute them. Instead, your application explicitly calls the tool execution API, giving you full control over:

• Which tool calls to execute
• User approval workflows
• Security validation
• Audit logging

The basic flow is: Chat Request → Review Tool Calls → Execute Tools → Continue Conversation.

---

Authentication

The /v1/mcp/tool/execute endpoint uses the same authentication as other inference endpoints like /v1/chat/completions: authenticate every request with your Virtual Key.

Pass the key in the Authorization header (or the x-bf-vk header):

-H "Authorization: Bearer sk-bf-your-virtual-key"
# or
-H "x-bf-vk: sk-bf-your-virtual-key"

For details on how virtual keys work and how to scope them, see Authentication and Virtual Keys.

---

End-to-End Example

Python SDK

The deepintshield Python SDK exposes a generic shield.mcp surface that works with any MCP server connected to your gateway. It includes adapters for OpenAI, Anthropic, and LangChain.

pip install 'deepintshield[openai]'

Direct call (skip the LLM)

from deepintshield import DeepintShield

shield = DeepintShield(
    virtual_key="sk-bf-...",
    base_url="https://app.deepintshield.com",
)

result = shield.mcp.call(
    server="DeepWiki",          # case-sensitive client name from MCP Registry
    tool="ask_question",        # bare tool name; the SDK adds the '<server>-' prefix
    repoName="facebook/react",
    question="What is Suspense?",
)
print(result.text)

OpenAI tool-calling loop

from deepintshield import DeepintShield, Tool

shield = DeepintShield(virtual_key="sk-bf-...", base_url="https://app.deepintshield.com")
openai = shield.openai()

tools = [
    Tool(server="DeepWiki", name="ask_question",
         description="Ask a question about a public GitHub repository.",
         schema={"type": "object",
                 "properties": {"repoName": {"type": "string"},
                                "question": {"type": "string"}},
                 "required": ["repoName", "question"]}),
]

messages = [{"role": "user", "content": "Summarize facebook/react's reconciler."}]
first = openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=shield.mcp.to_openai(tools),
    tool_choice="required",
)
assistant = first.choices[0].message
messages.append(assistant.model_dump(exclude_none=True))
messages.extend(shield.mcp.run_openai_tool_calls(assistant.tool_calls))

final = openai.chat.completions.create(model="gpt-4o-mini", messages=messages)
print(final.choices[0].message.content)

Note

The same tools list works with the Anthropic and LangChain adapters via shield.mcp.to_anthropic(tools) and shield.mcp.to_langchain(tools). See the SDK README for full examples.

Gateway

Step 1: Send Chat Request

curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "List files in the current directory"
      }
    ]
  }'

Response with tool calls:

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_xyz789",
        "type": "function",
        "function": {
          "name": "filesystem-list_directory",
          "arguments": "{\"path\": \".\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Note

Tool names are prefixed with the MCP client name (e.g., filesystem-list_directory). This ensures uniqueness across multiple MCP clients.

Step 2: Execute the Tool

The request body matches the tool call object from the response:

curl -X POST https://app.deepintshield.com/v1/mcp/tool/execute \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "call_xyz789",
    "type": "function",
    "function": {
      "name": "filesystem-list_directory",
      "arguments": "{\"path\": \".\"}"
    }
  }'

Tool result response:

{
  "role": "tool",
  "content": "[\"notes.txt\", \"app.py\", \"README.md\"]",
  "tool_call_id": "call_xyz789"
}

Step 3: Continue the Conversation

Assemble the full conversation history and continue:

curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "List files in the current directory"
      },
      {
        "role": "assistant",
        "content": null,
        "tool_calls": [{
          "id": "call_xyz789",
          "type": "function",
          "function": {
            "name": "filesystem-list_directory",
            "arguments": "{\"path\": \".\"}"
          }
        }]
      },
      {
        "role": "tool",
        "content": "[\"notes.txt\", \"app.py\", \"README.md\"]",
        "tool_call_id": "call_xyz789"
      }
    ]
  }'

Final response:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "The current directory contains 3 files:\n\n1. **notes.txt** - Text notes\n2. **app.py** - Application source file\n3. **README.md** - Documentation"
    },
    "finish_reason": "stop"
  }]
}

---

Response Formats

DeepIntShield supports two API formats for tool execution:

Chat Format (Default)

Use ?format=chat or omit the parameter:

POST /v1/mcp/tool/execute?format=chat

Request:

{
  "id": "call_xyz789",
  "type": "function",
  "function": {
    "name": "filesystem-read_file",
    "arguments": "{\"path\": \"notes.txt\"}"
  }
}

Response:

{
  "role": "tool",
  "content": "{\"key\": \"value\"}",
  "tool_call_id": "call_xyz789"
}

Responses Format

Use ?format=responses for the Responses API format:

POST /v1/mcp/tool/execute?format=responses

Request:

{
  "type": "function_call_output",
  "call_id": "call_xyz789",
  "name": "filesystem-read_file",
  "arguments": "{\"path\": \"notes.txt\"}"
}

Response:

{
  "type": "function_call_output",
  "call_id": "call_xyz789",
  "output": "{\"key\": \"value\"}"
}

---

Multiple Tool Calls

LLMs often request multiple tools in a single response. Each tool call carries its own id, so you can execute them one at a time and append every result to the conversation history before continuing.

With the Python SDK, pass the whole list of tool calls to the helper and it returns one tool-result message per call, ready to append:

messages.extend(shield.mcp.run_openai_tool_calls(assistant.tool_calls))

With the Gateway, send one POST /v1/mcp/tool/execute request per tool call and append each returned tool message to your conversation history.

---

Relationship authorization (ReBAC)

Beyond name-based allow-lists, DeepIntShield can authorize each MCP interaction against a relationship graph backed by OpenFGA, so access depends on who is related to what - ownership, team membership, and folder→document inheritance. A single tool call is checked at up to three stages:

Stage	Question	Example check
Connect	May this principal use this MCP server?	can_connect on mcp_server:<id>
Invoke	May this principal call this tool?	can_invoke on mcp_tool:<server>/<tool>
Resource	May this principal touch the record the tool acts on?	viewer on document:{args.path}

The Resource stage is the record-level gate an allow-list can’t express: read_file is allowed in general, but this principal may only read files they have a viewer relationship to. Each check is the same relationship policy operand, evaluated inline and folded into the decision cache, so it adds no latency to the common path. Server/tool bindings are managed from MCP Registry → Authorization; resource relationships come from your app data.

Plan availability

MCP relationship authorization (connect / invoke / resource) is available on Business and above; relationship-aware tools/list filtering and the least-privilege analytics are Enterprise. See Relationship Authorization (ReBAC) for the full model and setup.

---

Error Handling

Tool execution can fail for several reasons:

• The tool execution timed out
• The tool does not exist, or its MCP client is disconnected
• The tool is filtered out by configuration (tools_to_execute)

When execution fails, /v1/mcp/tool/execute returns an error response:

{
  "error": {
    "type": "tool_execution_error",
    "message": "Tool 'filesystem-delete_file' is not allowed for this request"
  }
}

---

Copy-Pastable Responses

Tool execution responses are designed to be appended directly to your conversation history. Each response already includes:

• The correct role field ("tool")
• A matching tool_call_id for correlation
• Properly formatted content

Append the returned message to your message list and send it back in your next chat request - no reshaping required.

---

Next Steps

Agent Mode

Enable autonomous tool execution with auto-approval

Open →

Tool Filtering

Control which tools are available per request

Open →