Investigate errors without a log platform
Use ssh_logs_search with file: app.log, query: timeout, levels: [ERROR], from: -15m and maxLines: 20. File names must already be selected in the connection.
APIs & logs · MCP integration
Give AI the log files it needs. Keep the rest out of scope.
Read text and JSON Lines on an SSH server without sending your AI a shell. Select the exact files, verify the host key, and let GateRook turn bounded read and search requests into controlled server commands.
Connection in GateRook
stage-server-logs
SSH log files
stage / QA- Connector type
- SSH log files
- Host / port / user
- app.stage.internal / 22 / logreader
- Authentication
- Private key file
- Private key file
- ~/.ssh/stage-logreader
The route
Your AI requests a tool. GateRook checks the endpoint policy, resolves credentials locally, and calls the configured service.
Understand the request flowAsk your AI
List the selected application logs on the staging server before investigating an error.
ssh_logs_list · arguments
{
"connection": "stage-server-logs"
}Example result
{
"root": "/var/log/orders",
"files": [
{
"file": "app.log",
"size": 1048576
},
{
"file": "worker.log",
"size": 262144
}
],
"truncated": false
}Sample configuration and output, not a live connection. Replace example values with your environment. Tool names here are connector names; the endpoint may expose a connection-specific name.
Put context to work
What you can do with SSH log files and AI
Inspect the end of a file
Call ssh_logs_read with file: app.log, tail: true and maxLines: 100. This reads a bounded snapshot; it does not open a live subscription.
Follow the evidence across pages
When scanComplete is false, repeat the same filters and limits, passing the returned nextCursor as cursor. Check warnings and diagnosticCountsComplete before treating an empty page as evidence that no matching events exist.
From service to MCP
How to connect SSH log files
GateRook must be running on a computer that can reach your service. Open Connections, choose Add connection, and select SSH log files. Give the connection a name and environment.
New to GateRook? Start with the full setup guide.Prepare a restricted log account
Give the account read access only to the relevant logs. The server needs SFTP, a POSIX shell, GNU or BSD head, tail, grep and stat, plus awk, cat, od and wc.
Connect and verify the server
Choose SSH log files, enter the host, port and user, and select password or local private-key authentication. Use Test connection and verify the server fingerprint before trusting it.
Select the files explicitly
Browse remote folders over SFTP, choose the root folder and select individual files. Configure text or JSON Lines parsing if needed, then test read access to the selected files.
Choose the endpoint and tool modes
Add the tested connection to an endpoint. In Tools & policies, enable only the tools needed for the task. Start with Read only where supported; use Approval for any selected mutation and leave other tools Off. A connection alone does not grant an AI client access.
Connect your AI and verify the first call
In Clients, choose your AI app and endpoint, review the connection details, and connect. Try this guide’s example in Playground before asking your AI. Open Activity to inspect the tool, target, decision and returned result. The getting started guide covers this shared flow.
Connection settings
Configure SSH log files in GateRook
These are example values for the connection form. Enter credentials into GateRook’s secret fields, not into an AI prompt. Requirements and alternatives are noted per field.
| Setting | Example | How to use it |
|---|---|---|
Connector type | SSH log files | A dedicated read-only connector, separate from SSH runbooks. |
Host / port / user | app.stage.internal / 22 / logreader | The account needs SFTP, SSH command execution and read access to the selected files. Connect from a machine with the required VPN or network access. |
Authentication | Private key file | Choose a local private-key file or password authentication. SSH policies may restrict the method; production defaults to private-key access. |
Private key file | ~/.ssh/stage-logreader | Use an absolute path or ~/ path. The key is read locally for authentication and is never uploaded. Enter an optional passphrase in GateRook. |
Host key | Verify the server fingerprint | Test connection and verify an unfamiliar fingerprint through a trusted channel before accepting it. Known-hosts entries can also be supplied. |
Remote log folder | /var/log/orders | Choose an absolute remote folder. Selecting the folder alone does not expose its contents. |
Allowed log files | app.log, worker.log | Select 1 to 500 exact paths relative to the folder. Files with new names, including rotated files, must be selected explicitly. |
Log format / time zone | auto / UTC | Auto detects JSON objects per line or text. Set the time zone for timestamps without an offset; optional JSON field names and timestamp patterns control parsing. |
Know what you expose
SSH log files tools and access boundaries
The connector determines what is possible. Endpoint modes and connection policies determine what a particular AI client may use.
| Tool | Purpose | Access behavior |
|---|---|---|
ssh_logs_list | List selected root-relative file names and sizes. Optional query, matchMode and caseSensitive filter names without reading their contents. | Read only; endpoint Approval can require a decision before a read. |
ssh_logs_read | Read one allowed file. Use tail and maxLines for recent records, or startLine/endLine for an inclusive physical line range. | Read only; file selection and output limits apply. |
ssh_logs_search | Search one, several or all selected files by literal text, RE2 regex, levels and event time. Use maxLines to bound results; pass the returned nextCursor as cursor to continue. | Read only; no AI-supplied shell command. |
Before you enable access
- Only explicitly selected regular files are eligible. Symbolic links, nonregular files and files with multiple hard links are rejected. New or rotated names are not automatically included.
- GateRook builds read-only commands from validated parameters. These tools cannot accept arbitrary shell commands, edit logs or execute saved SSH runbooks.
- Each physical UTF-8 line is one record. JSON Lines requires one object per line; stack-trace continuation lines do not automatically inherit timestamps. Compressed archives are not supported.
- Time filters apply to parsed event timestamps, not file modification time. Records without a usable timestamp or level do not match an explicit filter for that field.
- Source scanning, returned lines, response size and execution time are bounded separately. Use maxLines for a small answer; keep scanBytes unset unless you intentionally want a smaller scan budget.
- Cursor continuation checks the file snapshot. Rotation, truncation or detected changes can invalidate it; later appends do not extend the snapshot. Start a new query to inspect new records.
- GateRook does not create a persistent log-file copy. Returned records still go to the AI client, and Activity retains bounded, masked call previews under your retention policy.
GateRook stores local connection secrets encrypted and resolves them for connectors. Allowed tool results are returned to your AI client and may be processed by its provider. Scope the data you expose as well as the actions you allow.
Practical answers
SSH log files connection questions
Use Test connection to isolate service access problems. Use Playground and Activity to inspect endpoint permissions and tool calls.
How is this different from the SSH connector?
SSH runs saved runbooks with typed parameters. SSH log files exposes only file listing, reading and searching, using an explicit file selection and GateRook-generated read commands.
Can I use a local private key or Vault SSH CA?
This connector accepts a local private-key file, with an optional passphrase, or a password when the SSH policy allows it. Vault SSH CA is a feature of the separate SSH runbook connector.
Why does a healthy connection fail when reading one file?
Automatic health checks verify SSH, SFTP and the root folder. Test connection checks every selected file. Rotation or permission changes can make an individual file unavailable after either check; review the file selection and permissions.
Can I search more than one file?
Yes. Pass files with exact selected names, or omit both file and files to search the configured selection. file and files are mutually exclusive. Results follow file and byte order, not a global sort by timestamp.
Does a zero-match page mean there are no errors?
Not necessarily. If scanComplete is false, pass the returned nextCursor as cursor with the same filters and limits. Review warnings, skipped or unparsed records and diagnosticCountsComplete. A bounded or partially parsed scan is not proof that every source record was examined.
Keep exploring
Connect the rest of your stack
SSH
Use SSH from AI through GateRook MCP runbooks. Connect with keys, passwords or Vault SSH CA, verify host keys, and approve commands that change your servers.
Loki
Connect Loki to AI through MCP. Search and follow scoped logs with GateRook, using native queries, bounded time ranges and private credentials.
AWS CloudWatch Logs
Connect AWS CloudWatch Logs to AI through MCP. Search and follow scoped logs with GateRook, using native queries, bounded time ranges and private credentials.
Your infrastructure, on your terms
Bring SSH log files into the conversation.
Start with one connection. Choose what your AI can do.