Smithy

Smithy is Forge's AI developer assistant. Its MCP server exposes Smithy's orchestrator over the Model Context Protocol and also exposes deterministic documentation tools backed by Forge's shared documentation service.

This page documents Smithy's public MCP tool surface:

• ask
• search_docs
• get_doc

For the design rationale behind explicit conversation IDs and MCP structuredContent, see ADR 0014.

---

ask

Ask Smithy about the Forge developer platform, Azure DevOps pipelines, builds, work items, repositories, or developer workflows. Smithy routes to the appropriate specialist automatically.

Parameters

Parameter	Required	Type	Description
question	Yes	string	Your question for Smithy.
conversationId	No	string	Optional stable conversation identifier. Omit it for a one-shot question, or reuse the same value to continue a prior thread.

conversationId constraints

Constraint	Value
Minimum length	1 character
Maximum length	128 characters
Allowed characters	Letters, numbers, -, _
Idle expiration	30 days of inactivity

If conversationId is present but invalid, the tool returns an MCP error.

One-shot and multi-turn behavior

• One-shot: Omit conversationId. Smithy answers the question and does not read or write conversation history.
• Multi-turn: Reuse the same conversationId on later calls. Smithy only loads and persists history when the request includes both:
• a caller-supplied conversationId
• an authenticated Entra object identifier (oid)
• Unauthenticated calls: If the caller is not authenticated, Smithy treats the call as one-shot even when conversationId is supplied.
• Expired or missing conversations: If a supplied conversationId does not resolve to an existing conversation, Smithy starts a new one and returns a note in the structured response.

Response

ask returns the answer in two forms:

1. Plain text MCP tool content, so text-only clients continue to work unchanged
2. MCP structuredContent with the envelope below

{
  "answer": "Use the forge MCP tools for read-only CLI lookups before shelling out to saif.",
  "conversationId": "my-stable-id",
  "note": null
}

Field	Type	Description
answer	string	Smithy's plain-text answer.
conversationId	string or null	The active conversation ID when Smithy is actually using persisted conversation state. It is null for one-shot calls and unauthenticated calls.
note	string or null	Present only when Smithy could not load the requested conversation, such as when it was not found or expired after 30 days of inactivity.

Examples

One-shot call:

{
  "question": "How do I inspect Azure DevOps build logs from Forge?"
}

Multi-turn call:

{
  "question": "Continue from the last answer and show me the exact tool names.",
  "conversationId": "build-log-help"
}

---

search_docs

Searches the Forge platform documentation for relevant content. Use this tool to find documentation about Forge features, guides, and reference material. After finding relevant results, use get_doc to retrieve the full content of a specific document.

Parameters

Parameter	Required	Type	Description
query	Yes	string	Search query, such as terraform modules, authentication, or migration guide.
maxResults	No	integer	Maximum number of results to return. Default 10, maximum 25.

Response

search_docs returns a JSON array. Each array item has this shape:

[
  {
    "Title": "Calling Downstream APIs",
    "Path": "guides/development/calling-apis",
    "Url": "https://forge.saif.com/guides/development/calling-apis/",
    "Snippet": "Configure a Kiota client with scopes and authentication...",
    "Score": 0.92
  }
]

Field	Type	Description
Title	string	Document title.
Path	string	Document location path to pass to get_doc.
Url	string	Public Forge documentation URL.
Snippet	string	Matching excerpt.
Score	number	Search relevance score.

---

get_doc

Gets the full content of a specific Forge documentation page. Use this after search_docs and pass the location path from search results.

Parameters

Parameter	Required	Type	Description
location	Yes	string	Document location path, such as guides/development/getting-started or reference/version-compatibility.

Response

Successful lookups return a JSON object with this shape:

{
  "Location": "reference/version-compatibility",
  "Url": "https://forge.saif.com/reference/version-compatibility/",
  "Content": "# Version Compatibility\n..."
}

If the document is not found, get_doc returns:

{
  "NotFound": true,
  "Location": "reference/missing-page",
  "Message": "Document not found at location 'reference/missing-page'. Use 'search_docs' to find available documents."
}

Field	Type	Description
Location	string	Document location path.
Url	string	Public Forge documentation URL.
Content	string	Full markdown content of the document.
NotFound	boolean	Present only on not-found responses.
Message	string	Present only on not-found responses.