MCP: questions and answers
Questions about Talewright's MCP server: the endpoint, how tools are named and listed, every group of tools, resources, safe retries and how an agent does each common task. The rules are in MCP.
The basics
- What is MCP?
- Does Talewright have an MCP server?
- What is the address of Talewright's MCP server?
- How is the MCP server related to the REST API?
- Can an agent do something over MCP that it cannot do over REST?
- What does the MCP server offer besides tools?
- Does the MCP server have prompts?
- What does the MCP server call itself?
- What instructions does the MCP server give an agent?
- Can I use the MCP server with my browser session?
- What do I need in the app before I can use MCP?
Transport and protocol
- Which transport does the MCP server use?
- Does the MCP server use server-sent events or keep a stream open?
- Which HTTP method does an MCP request use?
- Does the MCP server keep a session?
- Does the MCP server use cookies?
- Does an
Originheader that names the Talewright app get through to/mcp? - Which MCP protocol versions does Talewright support?
- What happens when my MCP client offers an older protocol version?
- Do the tools differ between MCP protocol versions?
- What does
server/discoverreturn? - Can the MCP server notify my agent when a file changes?
- Does the tool list change while my agent is connected?
Authentication
- How does an MCP request authenticate?
- What does the MCP endpoint answer without a token?
- What does the MCP endpoint answer for an expired or revoked token?
- Do
initializeandtools/listcount against the rate limit? - What does Talewright record about my MCP client?
- What does an agent see when its key is revoked while it works?
How tools are named and listed
- How are the MCP tools named?
- What do the prefixes of the tool names mean?
- What is the difference between the
workspace_and thelibrary_tools? - Does every workspace tool have an organization folder version?
- Why is there a tool called
library_library_proposals_create? - Why does my agent see fewer than 65 tools?
- How many tools does each scope list?
- Which tools does a credential with only
workspace:readsee? - Which tools does a credential with only
files:approvesee? - Why are no tools listed for my agent?
- Why is one tool missing from my agent's list?
- Does the tool list follow my role?
- In what order does
tools/listreturn the tools? - Is the tool list paged?
- How do I keep my agent's tool list short?
- Is there a "current workspace" for the tools?
Arguments and results
- How are a tool's arguments shaped?
- What format do IDs and times have in tool arguments?
- Does an argument set to
nullcount as given? - Do the tools' input schemas use references?
- What does a successful tool call return?
- What does a tool return when its operation has no body?
- Where is the error code in a failed tool result?
- What should an agent do when a tool result is too large?
- How do the list tools page their results?
Tool hints
- Which annotations do Talewright's tools carry?
- Which tools are marked read-only?
- Which tools are marked destructive?
- Why is trashing marked destructive when it can be undone?
- Why is cancelling an upload not marked destructive?
- Which tools are safe to repeat?
- Which changing tool is not safe to repeat blindly?
- Does any Talewright tool reach outside Talewright?
Resources
Discovery tools
- Which tool should an agent call first?
- How does an agent find out which scopes it holds?
- How does an agent find out when its credential expires?
- Where does an agent get the
organizationIDfor thelibrary_tools? - Can an agent limited to some workspaces use the
library_tools? - Is the result of
workspaces_listpaged? - Can an agent tell which workspaces it lost access to?
The organization and its people
Statuses and fields
Finding and reading files
- How does an agent find a file?
- How does the search argument
qmatch? - How does an agent list the files of one folder?
- Can
folderID,rootandunderbe combined in one search? - Which file types can an agent filter by?
- How does an agent find files that have no status?
- How does an agent filter files by a field value?
- How does an agent find images without alt text?
- How does an agent find duplicate files?
- How does an agent list what is in the trash?
- How can an agent sort search results?
- How does an agent read one file in full?
- Can an agent read a file that is in the trash?
- What is the difference between
visibilityandpublicon a file? - How does an agent list a file's versions?
- How does an agent see a file's duplicates?
- Which tools work on files?
Downloading
- How does an agent download a file?
- Which variants can an agent ask a signed URL for?
- Should the download of a signed URL send the API key?
- Why is there no tool that returns a file's bytes?
- Can an agent download a ZIP of several files over MCP?
- What happens when an agent asks for a thumbnail of a font?
- What happens when an agent asks for a preview right after an upload?
Changing files
- How does an agent rename a file?
- How does an agent move a file to another folder?
- How does an agent add a tag to a file?
- Is there a tool that creates a tag?
- How does an agent set alt text, a caption or a description?
- How does an agent clear a file's alt text?
- How does an agent set a field value on one file?
- How does an agent set one field on many files at once?
- Can an agent set the status through
fields? - How does an agent set a status on files?
- What does
restrictedFileIDsmean in the result of a status change? - What does
confirmVisibilityChangedo? - What happens when an agent moves a file into a public folder?
- What does an agent need to move a file out of a public folder?
- How does an agent move a file to the trash?
- How does an agent restore a file from the trash?
- Why can an agent not restore a file that went to the trash with its folder?
- Can an agent change a file that is in the trash?
- What happens when one file in a batch of 100 is in the trash?
- Why is there no tool to make a file public?
- Why is there no tool to delete a file for good?
Folders
Tags
Uploads
- How does an agent upload a file?
- Do a file's bytes go through an MCP tool call?
- How does an agent upload a file of several gigabytes?
- Which tools work on uploads?
- Which arguments does
workspace_uploads_createtake? - What decides the type of an uploaded file?
- What should an agent send as
contentTypewhen it does not know the type? - What is the
sha256argument of an upload for? - How does an agent replace a file with a new version?
- How does an agent know that an upload finished?
- Which states can an upload have?
- What does an agent do when a part's address expired before it sent the part?
- What does an agent do when the
completecall times out? - What happens when an agent completes an upload before the bytes arrived?
- Is a file that an agent uploads public at once?
- How does an agent cancel an upload?
- How does an agent list its unfinished uploads?
- Who owns an upload that an agent started?
Library proposals
- What is a library proposal?
- When should an agent create a proposal and not change files directly?
- Which tools work on library proposals?
- How does an agent create a proposal?
- Which actions can a proposal item hold?
- What does the
payloadof a proposal item look like? - Can a proposal move a file into a folder that does not exist yet?
- Can a proposal change a file's status or make it public?
- What is
baseLockVersionon a proposal item? - What is the
rationaleof a proposal item? - Which states can a proposal and its items have?
- When does a proposal item become stale?
- What does
allowedActionshold for an agent? - Can an agent withdraw items of a proposal?
- Why is there no tool to apply a proposal?
- How does the person find the proposal an agent made?
- What happens to a proposal's items when their file is deleted for good?
- How does an agent list the proposals that are still open?
Safe retries
- Is
requestIDrequired on MCP tools? - What should an agent do when a create call times out?
- What happens when an agent reuses a
requestIDwith different arguments? - Can a
requestIDbe used again after the call was refused? - Do a workspace and the organization folder share request IDs for proposals?
- What is
expectedLockVersionfor? - What happens when an agent retries a rename whose answer was lost?
- What is
baseVersionIDfor?